How to Self-Host Planka with Docker Compose

What Is Planka?

Planka is a self-hosted Kanban board that recreates the Trello experience. Boards, lists, cards, labels, due dates, checklists, file attachments, and real-time collaboration — all running on your own server. It’s one of the cleanest open-source project management tools available, focused on doing Kanban well without feature bloat. (planka.app)

Prerequisites

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

Docker Compose Configuration

Create a directory for Planka and a docker-compose.yml file:

mkdir -p ~/planka && cd ~/planka

services:
  planka:
    image: ghcr.io/plankanban/planka:v2.0.2
    container_name: planka
    ports:
      - "3000:1337"
    environment:
      - BASE_URL=http://localhost:3000                        # Change to your domain/IP
      - SECRET_KEY=your-very-long-random-secret-key-here     # Generate: openssl rand -hex 32
      - DATABASE_URL=postgresql://planka:planka_secret@planka-db/planka
      - [email protected]                # Change this
      - DEFAULT_ADMIN_PASSWORD=changeme                      # Change this — use a strong password
      - DEFAULT_ADMIN_NAME=Admin
      - TRUST_PROXY=0                                        # Set to 1 if behind a reverse proxy
    volumes:
      - planka-avatars:/app/public/user-avatars
      - planka-backgrounds:/app/public/project-background-images
      - planka-attachments:/app/private/attachments
    depends_on:
      planka-db:
        condition: service_healthy
    restart: unless-stopped

  planka-db:
    image: postgres:16-alpine
    container_name: planka-db
    environment:
      - POSTGRES_USER=planka
      - POSTGRES_PASSWORD=planka_secret        # Match DATABASE_URL above
      - POSTGRES_DB=planka
    volumes:
      - planka-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "planka"]
      interval: 10s
      start_period: 30s
    restart: unless-stopped

volumes:
  planka-avatars:
  planka-backgrounds:
  planka-attachments:
  planka-db:

Important: Generate a proper SECRET_KEY before starting:

openssl rand -hex 32

Replace your-very-long-random-secret-key-here with the generated value.

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server:3000 in a browser
2. Log in with the admin credentials you set in DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD
3. Change your admin password immediately after first login
4. Create your first project and board

Planka creates the admin user on first startup using the DEFAULT_ADMIN_* environment variables. These are only used for initial creation — changing the env vars after first boot won’t update the existing admin account.

How Planka Works

Planka organizes work in a hierarchy:

Projects → Boards → Lists → Cards

• Projects are the top level — a team, a client, or a major initiative
• Boards are individual Kanban boards within a project (e.g., “Sprint 14”, “Marketing Tasks”)
• Lists are the columns on a board (e.g., “To Do”, “In Progress”, “Done”)
• Cards are individual tasks with descriptions, checklists, attachments, labels, due dates, and comments

Members are assigned at the project level. Everyone in a project can see all boards within it. There’s no per-board permission model.

Configuration

Reverse Proxy

If running behind a reverse proxy, set TRUST_PROXY=1 in the environment variables and update BASE_URL to your public domain:

environment:
  - BASE_URL=https://planka.yourdomain.com
  - TRUST_PROXY=1

For Nginx Proxy Manager or Caddy, point the proxy to http://planka:1337 (the internal container port).

Reverse Proxy Setup

Email Notifications

Planka sends email notifications for card assignments, comments, and due dates. Configure SMTP:

environment:
  - SMTP_HOST=smtp.gmail.com
  - SMTP_PORT=587
  - SMTP_SECURE=true
  - [email protected]
  - SMTP_PASSWORD=app-password-here
  - [email protected]

File Upload Limits

The default maximum upload size is 10 MB. Increase it for larger attachments:

environment:
  - MAX_UPLOAD_FILE_SIZE=52428800    # 50 MB in bytes

Features Worth Knowing

Real-time updates. Changes by one user appear instantly for others — no page refresh needed. WebSocket-based sync keeps all connected clients in sync.

Card timers. Start a timer on a card to track time spent. Useful for freelancers or teams tracking effort.

Board backgrounds. Custom background images per board. Cosmetic, but helps visually distinguish boards.

Markdown support. Card descriptions and comments support Markdown formatting.

Keyboard shortcuts. Navigate and manage cards without touching the mouse. Press ? to see available shortcuts.

Backup

Back up the PostgreSQL database and the attachment volumes:

# Database backup
docker exec planka-db pg_dump -U planka planka > planka-backup-$(date +%Y%m%d).sql

# Attachment volumes — back up the Docker volumes
docker run --rm -v planka-attachments:/data -v $(pwd):/backup alpine tar czf /backup/planka-attachments-$(date +%Y%m%d).tar.gz /data

To restore:

# Restore database
cat planka-backup-20260224.sql | docker exec -i planka-db psql -U planka planka

Backup Strategy

Troubleshooting

Planka won’t start — “SECRET_KEY is required”

Symptom: Container exits immediately with a secret key error. Fix: Generate a key with openssl rand -hex 32 and set it in the SECRET_KEY environment variable. It must be at least 32 characters.

Can’t log in after changing DEFAULT_ADMIN_EMAIL

Symptom: Changed the admin email env var but can’t log in with the new email. Fix: DEFAULT_ADMIN_* variables only apply on first boot. To change admin credentials after setup, log in with the original credentials and change them through the Planka UI.

Cards not syncing between users

Symptom: Changes made by one user don’t appear for others. Fix: Check that WebSocket connections aren’t being blocked by your reverse proxy. For Nginx, ensure proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade" are set.

File uploads failing

Symptom: Attachments fail to upload with no error message. Fix: Check the MAX_UPLOAD_FILE_SIZE environment variable. Also verify your reverse proxy isn’t limiting upload size (Nginx default is 1 MB — set client_max_body_size 50M;).

Resource Requirements

• RAM: ~80 MB idle (app + PostgreSQL), ~150 MB under active use
• CPU: Low — spikes only during file processing
• Disk: ~500 MB for the application, plus storage for attachments

Verdict

Planka is the best self-hosted Trello replacement if you want clean Kanban boards without the complexity of full project management tools like Plane or GitLab. The real-time collaboration works well, the UI is polished, and the Docker setup is straightforward.

It’s not the right choice if you need Gantt charts, time tracking reports, sprint planning, or CalDAV sync — look at Vikunja or Plane for those. But for teams that just need visual task boards, Planka does the job with minimal overhead.

Related

• Best Self-Hosted Project Management Tools
• Vikunja vs Planka
• Planka vs WeKan
• Focalboard vs Planka
• How to Self-Host Vikunja
• How to Self-Host Plane
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy