How to Deploy Kanboard on a VPS

copysudo apt-get update && sudo apt-get -y upgrade
sudo apt-get install -y curl openssl ufw dnsutils

copyadduser deploy
usermod -aG sudo deploy

copysudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable

#Install Docker

Kanboard is installed with Docker Compose. If Docker isn't on the server yet, the convenience script installs Docker Engine and the Compose plugin (the Docker and Compose on Ubuntu guide covers the details):

copycommand -v docker >/dev/null || curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
sudo docker compose version

The group change applies on your next login; until then the commands below use sudo docker.

#Install Kanboard

Create a project directory and generate a database password into a .env file that Compose reads automatically. The guard keeps the step safe to re-run: regenerating the password on an existing install would lock Kanboard out of its own database.

copymkdir -p ~/kanboard && cd ~/kanboard
[ -f .env ] || echo "DB_PASSWORD=$(openssl rand -hex 16)" > .env
grep -c DB_PASSWORD .env

Now the Compose file. It is the official PostgreSQL variant, with the image tag pinned (so an upgrade is a deliberate edit, not a surprise) and the app port bound to loopback:

copycd ~/kanboard
cat > docker-compose.yml <<'EOF'
services:
  app:
    image: kanboard/kanboard:v1.2.54
    restart: always
    ports: ["127.0.0.1:8080:80"]
    volumes: ["data:/var/www/app/data", "plugins:/var/www/app/plugins"]
    environment:
      DATABASE_URL: postgres://kanboard:${DB_PASSWORD}@db/kanboard
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:17
    restart: always
    environment:
      POSTGRES_USER: kanboard
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: kanboard
    volumes: ["db:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "kanboard"]
      start_period: 15s
      interval: 10s
      timeout: 5s
volumes:
  data:
  plugins:
  db:
EOF

Start it and wait for the board to answer. The first boot creates the database schema, so give it a moment:

copycd ~/kanboard
sudo docker compose up -d
for i in $(seq 1 30); do
  code=$(curl -s -o /dev/null -w '%{http_code}' -L http://127.0.0.1:8080/)
  [ "$code" = "200" ] && break
  sleep 3
done
echo "Kanboard answered HTTP $code"
sudo docker compose ps

HTTP 200 and both containers running (the database healthy) means the install worked. If it never answers, jump to Troubleshooting.

#HTTPS + domain

Create an A record for your board's hostname (say kanban.example.com) pointing at the server's public IP, and confirm it resolves before requesting a certificate:

copydig +short kanban.example.com

Then put Automatic HTTPS with Caddy in front of the app. The simplest route is Caddy as a third service in the same Compose file, so it reaches the app by name. In docker-compose.yml, add this service under services::

copy  caddy:
    image: caddy:2
    restart: always
    ports: ["80:80", "443:443"]
    volumes: ["./Caddyfile:/etc/caddy/Caddyfile", "caddy_data:/data"]
    depends_on: [app]

Add caddy_data: to the volumes: list at the bottom, and remove the ports: line from the app service so the board is no longer published on the host. The Caddyfile next to the Compose file is one block:

copykanban.example.com {
    reverse_proxy app:80
}

Apply it with sudo docker compose up -d. Caddy requests the certificate on the first request and renews it on its own. Open https://kanban.example.com and confirm the padlock before you sign in.

#First login and hardening

Kanboard ships with a default administrator, admin / admin. That is public knowledge, so before anything else:

1. Sign in and open My profile from the user menu. Change the password to a long random one.
2. Go to Settings → Application settings and set the application URL to your HTTPS address, so notification emails link to the right place.
3. Create real user accounts for your team instead of sharing the admin login, and keep the administrator role for the few people who manage settings.
4. If you won't use the JSON-RPC API, leave it unconfigured; if you do, use a dedicated API token rather than the admin password.

#Backups

State lives in named volumes: the PostgreSQL data and Kanboard's data volume (file attachments and cached files). Back up both. Start with a logical database dump, which is portable across PostgreSQL versions:

copycd ~/kanboard
sudo docker compose exec -T db pg_dump -U kanboard kanboard > kanboard-db-$(date +%F).sql
test -s kanboard-db-$(date +%F).sql && ls -lh kanboard-db-*.sql

Then archive the attachments volume and the Compose files:

copycd ~/kanboard
sudo docker run --rm -v kanboard_data:/data -v "$PWD":/backup alpine \
  tar czf "/backup/kanboard-files-$(date +%F).tar.gz" -C /data .
sudo tar czf "kanboard-config-$(date +%F).tar.gz" docker-compose.yml .env
ls -lh kanboard-files-*.tar.gz kanboard-config-*.tar.gz

Copy these files off the server — object storage, another machine, anywhere that survives this VPS dying — and run the pair from cron. To restore, bring up only the database (sudo docker compose up -d db), pipe the dump back in with sudo docker compose exec -T db psql -U kanboard kanboard, unpack the files archive into the data volume, then start everything. Do that once on a scratch box so you know it works.

#Upgrades

Because the image tag is pinned, an upgrade is an edit. Check Kanboard's release notes, take a backup (previous section), change the tag in docker-compose.yml, then pull and recreate:

copycd ~/kanboard
sudo docker compose pull
sudo docker compose up -d
sudo docker compose logs --tail 20 app

Kanboard runs its database migrations automatically on the first start of a new version, and those are one-way, which is why the backup comes first. Keep the postgres major version pinned too; moving to a new PostgreSQL major is a dump-and-restore job, not a tag bump. Plugins in the plugins volume must support the version you upgrade to, so check them after the core update.

#Troubleshooting

The board returns 502 through Caddy, or never answers. Check sudo docker compose ps: if app is restarting, read sudo docker compose logs app. The usual cause is a wrong DATABASE_URL, which happens when .env was regenerated after the database volume already existed with the old password. Restore the original .env, or remove the volumes if the install holds no data yet.

Caddy never gets a certificate. Confirm dig +short kanban.example.com returns the server's IP and that your provider's network-level firewall, not just ufw, allows inbound 80 and 443. A blocked port 80 silently breaks the ACME challenge.

You can't sign in after changing the admin password. Kanboard has no email-based reset until SMTP is configured, so store the new password in your password manager the moment you set it, and keep a second administrator account so one lost password never locks everyone out.

Attachments disappear after recreating the stack. The volumes were removed (docker compose down -v). Plain docker compose down keeps them; the -v flag deletes them.

#Verification + next steps

Not exercised in our test run: the new-user step and the DNS check against your real domain (we ran on a throwaway box with a temporary hostname).

You're done when https://kanban.example.com loads with a valid certificate, you can sign in with a password that is not admin, docker compose ps shows every service up after a reboot (restart: always brings them back), and you have restored a backup onto a scratch box at least once.

From there, create your first project, set up columns and swimlanes, add automatic actions to move cards on events, and browse the plugin directory for integrations. For the ranked server picks and the app's catalog details, see Best VPS for self-hosting and the Kanboard entry.