Self-Hosting

Your data. Your server. Your rules.

Visiban is designed for self-hosting from day one. One command brings up Postgres, Valkey, and a reverse proxy — nothing leaves your infrastructure.

Requirements

A Linux server with Docker and Docker Compose v2. Minimum 2 vCPU / 4 GB RAM / 40 GB SSD — 1 GB will OOM under load.

24+

Docker

Compose

Postgres (bundled)

Valkey (bundled)

Site admin panel showing registration modes

Board settings rules tab showing WIP limit enforcement

Quick start

Clone the repo

$ git clone --branch v1.2.0 https://gitlab.com/visiban/visiban && cd visiban

Configure environment

$ cp .env.example .env
# Edit .env — set DJANGO_SECRET_KEY and SITE_DOMAIN at minimum

3
Start the stack
```
$ docker compose up --build -d
```

Retrieve the one-time admin password

$ docker compose exec backend cat /tmp/visiban_admin_password

Open the app

# Visit http://localhost:5173 and sign in with the password above

Docker image tags

Visiban publishes images to GHCR (ghcr.io/visiban/visiban). Each release is published under three tags, depending on how much control you want over updates.

:1.2recommended

Minor release line

Takes every 1.2.x patch automatically and stays on 1.2 after the next minor release ships, so you choose when to take a minor upgrade. Never points at a pre-release. Recommended for production.

:v1.2.0

Exact release

One immutable release. Use it for fully reproducible deploys, and change the tag yourself to upgrade.

:latest

Most recent release

Tracks the newest stable release and moves to the next minor version as soon as it ships. Pre-releases never get this tag.

Production deployment

For production, use docker-compose.prod.yml — it adds an Nginx reverse proxy, serves the built frontend as static files, and uses daphne (ASGI) for WebSockets.

Set APP_VERSION in your .env to control which image is pulled — use the minor-line tag to receive patch updates automatically:

# .env — follow the 1.2 line and take its patch releases (recommended)
APP_VERSION=1.2

# Or pin to an exact version for fully reproducible deploys
# APP_VERSION=v1.2.0

$ docker compose -f docker-compose.prod.yml up --build -d

⚠ Required for any non-localhost hostnameWhether on a LAN IP, internal domain, or public domain, set all four in .env before starting. Missing any one causes API failures or a WebSocket stuck on Reconnecting.

ALLOWED_HOSTS — your hostname or IP
CORS_ALLOWED_ORIGINS — full origin the browser uses
SITE_DOMAIN — hostname for OAuth callbacks
FRONTEND_URL — full URL allauth redirects to after OAuth

TLS termination can be handled by Nginx with Let's Encrypt — see the full installation guide for the complete checklist.

Kubernetes / Helm

A Helm chart is included under helm/visiban/.

$ helm dependency update helm/visiban
$ cp helm/visiban/values.secret.yaml.example helm/visiban/values.secret.yaml
# Edit values.secret.yaml — set djangoSecretKey and postgres password
$ helm install visiban helm/visiban \
    --namespace visiban --create-namespace \
    -f helm/visiban/values.secret.yaml \
    --set backend.image.tag=1.2 \
    --set frontend.image.tag=1.2 \
    --set ingress.host=boards.example.com \
    --set backend.settings.allowedHosts=boards.example.com \
    --set backend.settings.corsAllowedOrigins=https://boards.example.com \
    --set backend.settings.frontendUrl=https://boards.example.com \
    --set backend.settings.siteDomain=boards.example.com

After install, retrieve the one-time admin password:

$ kubectl exec -n visiban $(kubectl get pods -n visiban \
    -l app.kubernetes.io/component=backend -o jsonpath='{.items[0].metadata.name}') \
    -- cat /run/visiban/admin_password

Need the complete guide? The docs cover upgrades, backups, OAuth setup, and every environment variable.

Read the full docs →