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.51
    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.51
    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

Open http://your-server-ip:8080 in your browser
Log in with the default credentials:
- Username: admin
- Password: admin
Change the admin password immediately — go to the user icon → My Profile → Change Password
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.

FAQ

How does Kanboard compare to Trello?

Kanboard covers the core Kanban workflow — columns, cards, drag-and-drop — without Trello’s power-ups, Butler automations, or mobile apps. The trade-off is simplicity and control: Kanboard is self-hosted, free, and runs on 80 MB of RAM. Trello’s free tier now limits boards and power-ups. For teams that just need columns and cards, Kanboard delivers without SaaS lock-in.

Can Kanboard handle multiple projects?

Yes. Create unlimited projects, each with its own board, columns, swimlanes, and team members. Projects are fully independent. Users can be assigned to specific projects with different permission levels (manager, member, viewer).

Does Kanboard have a mobile app?

No official mobile app exists. The web interface is responsive and works on mobile browsers, but it’s not optimized for small screens. If mobile access is important, Vikunja or Planka offer better mobile experiences.

Can I integrate Kanboard with other tools?

Yes. Kanboard has a full JSON-RPC API for automation, webhook support for event notifications, and a plugin system for custom integrations. Community plugins add integrations with Slack, Mattermost, GitLab, and more. The API supports creating tasks, moving cards, and querying project data programmatically.

Is Kanboard actively maintained?

Kanboard is a mature project with infrequent releases — it’s feature-complete rather than abandoned. The core codebase is stable. New releases focus on bug fixes and minor improvements rather than major features. The PHP codebase is straightforward, making it easy to maintain custom installations.

Should I use SQLite or PostgreSQL with Kanboard?

SQLite for solo use or small teams (under 10 users). PostgreSQL for larger teams with concurrent access. SQLite handles reads well but can lock on concurrent writes. PostgreSQL eliminates this bottleneck. For most homelabs, SQLite is sufficient and eliminates the database container entirely.