How to Deploy Planka - Open-Source Project Management Tool

Planka is an open-source, Kanban-style project management platform used to organize tasks, work together with teams, and track project progress. It provides a web interface for managing boards, lists, and cards. Planka is widely used for software development, team task management, and product roadmap planning.

This article explains how to deploy Planka on a Linux server using Docker Compose, with a PostgreSQL backend and Traefik providing automatic HTTPS. It covers directory setup, environment variable configuration, deployment, creating a secure administrator account, and demonstrating core task management features through the web interface.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server (with at least 2 CPU cores and 4 GB of RAM) as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Create a DNS A record pointing to your server's IP address (for example, planka.example.com).

Set Up the Directory Structure, Configuration, and Environment Variables

Planka requires a configuration file to define environment variables, database connections, and application settings. The setup includes persistent storage for project boards and user assets to ensure data is retained across server restarts, and uses Traefik to automatically secure the web interface with HTTPS.

1. Create the project directory.

   CONSOLE

   Copy

   $ mkdir ~/planka

   Explain Code

   Powered by Vultr AgentBeta

2. Navigate to the project directory.

   CONSOLE

   Copy

   $ cd ~/planka

   Explain Code

   Powered by Vultr AgentBeta

3. Generate a secure secret key for the Planka application.

   CONSOLE

   Copy

   $ openssl rand -hex 64

   Explain Code

   Powered by Vultr AgentBeta

   Save the output for use in the environment file.

4. Create an environment file to store configuration variables.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

5. Add the following configuration. Replace planka.example.com with your domain name, admin@example.com with your email address, YOUR_GENERATED_SECRET_KEY with the output from the previous openssl command, and STRONG_DATABASE_PASSWORD with a secure password.

   INI

   Copy

   DOMAIN=planka.example.com
   LETSENCRYPT_EMAIL=admin@example.com
   
   # Planka Settings
   BASE_URL=https://planka.example.com
   SECRET_KEY=YOUR_GENERATED_SECRET_KEY
   
   # Database Settings
   POSTGRES_DB=planka
   POSTGRES_USER=planka_admin
   POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

Deploy with Docker Compose

The deployment stack consists of Traefik for reverse proxy and certificate management, plus the Planka container with mounted configuration and databases. This configuration uses the official Planka container image version 2.1.1.

1. Create the Docker Compose manifest.

   CONSOLE

   Copy

   $ nano docker-compose.yml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following content.

   YAML

   Copy

   services:
     traefik:
       image: traefik:v3.7.0
       restart: unless-stopped
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
         - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - ./letsencrypt:/letsencrypt
   
     postgres:
       image: postgres:16-alpine
       container_name: planka-db
       restart: unless-stopped
       environment:
         POSTGRES_DB: ${POSTGRES_DB}
         POSTGRES_USER: ${POSTGRES_USER}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       volumes:
         - ./pgdata:/var/lib/postgresql/data
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
         interval: 10s
         timeout: 5s
         retries: 5
   
     planka:
       image: ghcr.io/plankanban/planka:2.1.1
       container_name: planka-app
       depends_on:
         postgres:
           condition: service_healthy
       environment:
         BASE_URL: ${BASE_URL}
         DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres/${POSTGRES_DB}
         SECRET_KEY: ${SECRET_KEY}
       volumes:
         - ./data:/app/data
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.planka.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.planka.entrypoints=websecure"
         - "traefik.http.routers.planka.tls.certresolver=letsencrypt"
       restart: unless-stopped
   

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   In the above manifest:

   • traefik: Serves as the reverse proxy and TLS termination point. It listens on ports 80 and 443, automatically redirects HTTP to HTTPS, and provisions Let's Encrypt certificates.
   • postgres: Runs PostgreSQL 16 as the primary database for storing project boards, lists, tasks, and user profiles.
   • planka: Runs the Planka web application server and provides the Kanban board interface.

3. Launch the containers.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

4. Verify that the services are running.

   CONSOLE

   Copy

   $ docker compose ps -a

   Explain Code

   Powered by Vultr AgentBeta

   The output displays all containers in an Up state, with a healthy status shown for planka-db because it is the only service with a configured health check.

5. Create the administrator account.

   CONSOLE

   Copy

   $ docker compose run --rm planka npm run db:create-admin-user

   Explain Code

   Powered by Vultr AgentBeta

   When prompted, enter your administrator email, password, and name. Optionally, enter a username.

6. View the service logs to confirm Planka loaded the configuration successfully.

   CONSOLE

   Copy

   $ docker compose logs

   Explain Code

   Powered by Vultr AgentBeta

   The output displays PostgreSQL accepting connections and Planka starting without errors.

For more information on managing a Docker Compose stack, see the How to Use Docker Compose article.

Access and Configure Planka

After deployment, access the Planka web interface to log in with the administrator account and configure the workspace.

1. Replace planka.example.com with your configured domain and open https://planka.example.com in a web browser.

   

2. Enter the administrator email and password you created in the previous step.

3. Click Log in.

4. On the End User Terms of Service screen, check the I have read and accept these End User Terms of Service checkbox and click Continue to access the main project dashboard.

Application Use Case

The following steps create a basic Kanban board, populate it with tasks, and grant access to a team member to verify that the application's core features are functional.

Create a Project

Projects are the top-level container for boards in Planka.

1. Click Create project in the My Own section.
2. Enter a project name such as Team Collaboration Project.
3. Optionally, add a short project description.
4. Click Create project to create the project workspace.

Create a Board

A board holds the lists and cards that track work within a project.

1. Open the newly created project workspace.
2. Click Create board.
3. Enter a board name such as Development Tasks.
4. Click Create board to create the Kanban workspace.

Add Lists and Cards

Lists represent workflow stages, and cards represent individual tasks within them.

1. Open the Development Tasks board.

2. Click Add list to create workflow columns.

3. Create the following workflow lists:

   • To Do
   • In Progress
   • Completed

4. Click Add card under the To Do list, enter a task name such as Set up CI pipeline, and press Enter.

5. Repeat to add cards to the In Progress and Completed lists.

6. Drag a card from one list to another to verify that task movement works correctly.

   

Invite a Test Team Member

Adding a user account and granting it board access verifies that Planka's collaboration features work as expected.

1. Click your profile avatar in the top-right corner and select Administration from the User Actions menu.
2. Click Add user.
3. Enter the user details:
   • Name
   • Email Address
   • Password
4. Click Add User.
5. Return to the Development Tasks board.
6. Open the board members panel.
7. Search for the newly created user and add them to the board.

This confirms that the application can handle real-time collaboration and user access control across the domain.

Conclusion

You have deployed Planka on a Linux server using Docker Compose with Traefik for automatic HTTPS and PostgreSQL for persistent data storage. The setup provides a self-hosted Kanban board platform with real-time collaboration and user access control. For advanced features including custom branding, OIDC integration, and email notifications, refer to the official Planka documentation.