Self-Hosting Kanboard with Docker Compose

What Is Kanboard?

Kanboard is a minimalist Kanban project management tool focused on simplicity and efficiency. It replaces Trello for teams that want a self-hosted, no-frills task board without the bloat of enterprise tools. The project is open-source (MIT license) and runs on PHP with SQLite, MySQL, or PostgreSQL as a backend — making it one of the lightest project management tools you can self-host.

Official site: kanboard.org

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 512 MB of free RAM (256 MB minimum)
• 1 GB of free disk space
• A domain name (optional, for remote access)

Docker Compose Configuration

Kanboard supports three database backends. SQLite is the simplest — no separate database container needed. For teams larger than 10, use PostgreSQL.

Option 1: SQLite (Simplest)

Create a docker-compose.yml file:

services:
  kanboard:
    image: kanboard/kanboard:v1.2.50
    container_name: kanboard
    ports:
      - "8080:80"
    volumes:
      - kanboard-data:/var/www/app/data
      - kanboard-plugins:/var/www/app/plugins
    environment:
      DB_DRIVER: sqlite
      LOG_DRIVER: stdout
    restart: unless-stopped

volumes:
  kanboard-data:
  kanboard-plugins:

Option 2: PostgreSQL (Recommended for Teams)

services:
  kanboard:
    image: kanboard/kanboard:v1.2.50
    container_name: kanboard
    ports:
      - "8080:80"
    volumes:
      - kanboard-data:/var/www/app/data
      - kanboard-plugins:/var/www/app/plugins
    environment:
      DB_DRIVER: postgres
      DB_HOSTNAME: db
      DB_PORT: "5432"
      DB_NAME: kanboard
      DB_USERNAME: kanboard
      DB_PASSWORD: change-this-password    # CHANGE THIS
      DB_RUN_MIGRATIONS: "true"
      LOG_DRIVER: stdout
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    container_name: kanboard-db
    environment:
      POSTGRES_USER: kanboard
      POSTGRES_PASSWORD: change-this-password    # MATCH above
      POSTGRES_DB: kanboard
    volumes:
      - kanboard-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kanboard"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  kanboard-data:
  kanboard-db:
  kanboard-plugins:

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server-ip:8080 in your browser
2. Log in with the default credentials:
   • Username: admin
   • Password: admin
3. Change the admin password immediately — go to the user icon → My Profile → Change Password
4. Create your first project from the dashboard

There is no setup wizard. Kanboard drops you straight into a working instance.

Key Features

Feature	Details
Kanban boards	Drag-and-drop task management with customizable columns
Swimlanes	Horizontal groupings to organize tasks by priority, team, or type
Time tracking	Built-in timer per task — no plugins needed
Gantt charts	Visual timeline for project planning
Subtasks	Break tasks into smaller units with individual assignees
Tags & categories	Color-coded labels for filtering
Automatic actions	Trigger actions on events (e.g., move task → assign user)
Plugins	Extend via PHP plugins for integrations
API	Full JSON-RPC API for automation
LDAP/SSO	Built-in LDAP authentication support

Configuration

Key environment variables for customization:

Variable	Default	Purpose
PLUGIN_INSTALLER	false	Enable in-app plugin installation
MAIL_TRANSPORT	mail	Email transport (smtp for SMTP relay)
MAIL_SMTP_HOSTNAME	—	SMTP server address
MAIL_SMTP_PORT	25	SMTP port
MAIL_SMTP_USERNAME	—	SMTP auth username
MAIL_SMTP_PASSWORD	—	SMTP auth password
MAIL_SMTP_ENCRYPTION	—	tls or ssl
MAIL_FROM	[email protected]	Sender address

Email Notifications

To receive task notifications, add SMTP settings to your docker-compose.yml:

environment:
  MAIL_TRANSPORT: smtp
  MAIL_SMTP_HOSTNAME: smtp.gmail.com
  MAIL_SMTP_PORT: "587"
  MAIL_SMTP_ENCRYPTION: tls
  MAIL_SMTP_USERNAME: [email protected]
  MAIL_SMTP_PASSWORD: your-app-password
  MAIL_FROM: [email protected]

Reverse Proxy

Place Kanboard behind a reverse proxy for HTTPS access. Example Nginx configuration:

server {
    listen 443 ssl;
    server_name kanboard.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

See the full Reverse Proxy Setup guide for Nginx Proxy Manager and Caddy options.

Backup

Back up these volumes to preserve all data:

• kanboard-data — task data, attachments, SQLite database (if using SQLite)
• kanboard-plugins — installed plugins
• kanboard-db — PostgreSQL data (if using PostgreSQL)

# Stop containers before backup
docker compose stop

# Back up volumes
docker run --rm -v kanboard-data:/data -v $(pwd):/backup alpine tar czf /backup/kanboard-data.tar.gz -C /data .

# Restart
docker compose up -d

For automated backups, see the Backup Strategy guide.

Troubleshooting

Cannot log in with default credentials

Symptom: admin/admin login fails on fresh install.

Fix: The database may not have initialized. Check logs:

docker compose logs kanboard

Look for migration errors. If using PostgreSQL, ensure the database container started before Kanboard — the depends_on with healthcheck handles this.

Plugins directory not writable

Symptom: “Unable to install plugin” error in the UI.

Fix: Ensure the plugins volume is mounted and writable. Check ownership:

docker compose exec kanboard ls -la /var/www/app/plugins

The directory must be owned by nginx:nginx inside the container.

Self-signed certificate warnings

Symptom: Browser shows SSL warning when accessing via HTTPS.

Fix: Kanboard’s built-in HTTPS uses auto-generated self-signed certificates. Either accept the warning or use a reverse proxy with Let’s Encrypt certificates instead.

Resource Requirements

• RAM: ~80 MB idle, ~200 MB under load with 10+ concurrent users
• CPU: Low — handles most workloads on a single core
• Disk: ~100 MB for the application, plus storage for file attachments

Kanboard is one of the lightest project management tools available. It runs comfortably on a Raspberry Pi.

Verdict

Kanboard is the best self-hosted option for teams that want a dead-simple Kanban board without enterprise overhead. It’s fast, lightweight, and does one thing well. If you need sprints, velocity tracking, or Gantt-based project planning at scale, look at Plane or Vikunja instead. But for straightforward task management where you just need columns and cards, Kanboard nails it.

Related

• Best Self-Hosted Task Management Tools
• Best Self-Hosted Project Management Tools
• Plane vs Planka: Which Should You Self-Host?
• How to Self-Host Vikunja
• How to Self-Host Planka
• How to Self-Host Focalboard
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy