Self-Hosting Planka: A Beautiful Trello Alternative with Docker

If Trello’s pricing changes and data policies have you looking for alternatives, Planka is one of the best self-hosted Kanban boards available. It’s clean, fast, supports real-time collaboration, and runs beautifully in Docker.

What is Planka?

Planka is an open-source, self-hosted project management tool built around Kanban boards. Think Trello, but running on your own hardware with no account limits, no feature gates, and no subscription fees.

Why Self-Host Your Project Management?

• Privacy: Your project data stays on your server
• No user limits: Add your entire team without per-seat pricing
• No feature restrictions: All features available out of the box
• Real-time sync: Changes appear instantly across all connected users
• Markdown support: Rich card descriptions with full markdown editing
• 100+ notification providers: Slack, Discord, email, and more
• SSO support: OpenID Connect integration for enterprise environments

Prerequisites

Before starting, you’ll need:

• A Linux server (Ubuntu 22.04+ or Debian 12+ recommended)
• Docker and Docker Compose installed
• At least 1GB of RAM (2GB+ recommended for teams)
• A domain name (optional, but recommended for remote access)

Install Docker (if needed)

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect.

Step 1: Create the Project Directory

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

Step 2: Generate a Secret Key

Planka requires a secret key for session encryption. Generate one:

openssl rand -hex 32

Copy the output — you’ll need it in the next step.

Step 3: Create the Docker Compose File

Create docker-compose.yml:

version: "3.8"

services:
  planka:
    image: ghcr.io/plankanban/planka:latest
    container_name: planka
    restart: unless-stopped
    ports:
      - "3000:1337"
    environment:
      - BASE_URL=http://localhost:3000
      - DATABASE_URL=postgresql://planka:planka_password@planka-db:5432/planka
      - SECRET_KEY=YOUR_GENERATED_SECRET_KEY
      - [email protected]
      - DEFAULT_ADMIN_PASSWORD=ChangeMeNow123!
      - DEFAULT_ADMIN_NAME=Admin
      - DEFAULT_ADMIN_USERNAME=admin
    volumes:
      - planka-user-avatars:/app/public/user-avatars
      - planka-project-backgrounds:/app/public/project-background-images
      - planka-attachments:/app/private/attachments
    depends_on:
      planka-db:
        condition: service_healthy

  planka-db:
    image: postgres:16-alpine
    container_name: planka-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=planka
      - POSTGRES_USER=planka
      - POSTGRES_PASSWORD=planka_password
    volumes:
      - planka-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U planka -d planka"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  planka-user-avatars:
  planka-project-backgrounds:
  planka-attachments:
  planka-db-data:

Replace YOUR_GENERATED_SECRET_KEY with the key from Step 2. Change the admin credentials to something secure.

Step 4: Start Planka

docker compose up -d

Wait about 30 seconds for the database to initialize, then open http://your-server-ip:3000 in your browser.

Log in with the admin email and password you set in the compose file.

Step 5: Initial Configuration

Once logged in:

1. Change your password — The default password in the compose file is just for first login
2. Create a project — Click the + button to create your first project
3. Add a board — Each project can have multiple boards
4. Create lists — Add columns like “To Do”, “In Progress”, “Done”
5. Add cards — Click + on any list to create tasks

Adding Team Members

Click the settings icon in the top-right corner to access user management. You can create accounts for team members directly — no email verification server required.

Setting Up a Reverse Proxy

For remote access with HTTPS, put Planka behind a reverse proxy. Here’s a quick Nginx config:

server {
    listen 443 ssl http2;
    server_name planka.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/planka.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/planka.yourdomain.com/privkey.pem;

    client_max_body_size 120M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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;

        # WebSocket support for real-time updates
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Important: Update BASE_URL in your compose file to match your domain (https://planka.yourdomain.com) and restart the container.

The client_max_body_size directive controls the maximum file upload size — adjust as needed.

Configuring Notifications

Planka supports notifications through over 100 providers using the Shoutrrr library. Add notification URLs to your environment:

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

For Slack or Discord notifications, you can use webhook URLs in the notification settings within the Planka UI.

Enabling SSO with OpenID Connect

If you run Authentik, Keycloak, or another OIDC provider, add these environment variables:

environment:
  - OIDC_ISSUER=https://auth.yourdomain.com/application/o/planka/
  - OIDC_CLIENT_ID=your-client-id
  - OIDC_CLIENT_SECRET=your-client-secret
  - OIDC_SCOPES=openid profile email
  - OIDC_ADMIN_ROLES=admin
  - OIDC_ROLES_ATTRIBUTE=groups

This lets your team log in with their existing identity provider credentials.

Backup Strategy

Database Backup

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

Full Backup (Database + Files)

#!/bin/bash
BACKUP_DIR=~/backups/planka/$(date +%Y%m%d)
mkdir -p "$BACKUP_DIR"

# Database
docker exec planka-db pg_dump -U planka planka > "$BACKUP_DIR/database.sql"

# Volumes
docker run --rm -v planka_planka-attachments:/data -v "$BACKUP_DIR":/backup alpine tar czf /backup/attachments.tar.gz -C /data .
docker run --rm -v planka_planka-user-avatars:/data -v "$BACKUP_DIR":/backup alpine tar czf /backup/avatars.tar.gz -C /data .

echo "Backup complete: $BACKUP_DIR"

Run this weekly with a cron job for peace of mind.

Troubleshooting

Container Won’t Start

Check logs:

docker compose logs planka

Common issues:

• Database not ready: The healthcheck should handle this, but if not, restart with docker compose restart planka
• Port conflict: Change 3000:1337 to another port like 3001:1337
• Missing secret key: Make sure SECRET_KEY is set — Planka won’t start without it

Real-Time Updates Not Working

If changes aren’t syncing between users, your reverse proxy likely isn’t forwarding WebSocket connections. Make sure the Upgrade and Connection headers are set (see the Nginx config above).

Can’t Upload Large Files

Increase client_max_body_size in your Nginx config and restart Nginx. The default is usually 1MB, which is too small for most attachments.

Forgot Admin Password

Reset it by updating the environment variables and recreating the container:

docker compose down
# Update DEFAULT_ADMIN_PASSWORD in docker-compose.yml
docker compose up -d

Planka vs Trello vs Other Self-Hosted Options

Planka stands out for its clean UI — it genuinely feels like a premium SaaS product, which is rare for self-hosted tools.

Conclusion

Planka gives you a polished, real-time Kanban board without the SaaS dependency. It’s lightweight enough to run on a Raspberry Pi yet powerful enough for team collaboration with SSO and notifications.

The setup takes about five minutes with Docker Compose, and you get unlimited users, unlimited boards, and full control over your data. For anyone already self-hosting other services, adding Planka to your stack is a no-brainer.

Useful links:

• Planka GitHub Repository
• Planka Documentation
• Docker Documentation