# Planka Kanban Board

> Planka Trello alternative with PostgreSQL.

- Category: Productivity & Collaboration
- Difficulty: beginner
- Components: planka, postgresql
- Tags: planka, kanban, trello, project-management
- Source: https://docker.recipes/productivity/planka-kanban-stack

## Overview

Planka is an open-source Kanban board application that provides a self-hosted alternative to Trello, developed with a focus on simplicity, performance, and team collaboration. Built with Node.js and React, Planka offers the familiar drag-and-drop interface of popular project management tools while giving organizations complete control over their data and deployment. The platform supports real-time collaboration, file attachments, due dates, labels, and member assignments, making it suitable for teams of all sizes looking to organize projects without relying on external services.

This deployment creates a two-container stack with Planka running on port 1337 and a dedicated PostgreSQL 15 database instance for data persistence. The Planka service connects to the planka-db container using a PostgreSQL connection string, with separate Docker volumes for user avatars, project background images, file attachments, and database data. This architecture ensures clean separation between the application layer and data storage while maintaining optimal performance for board operations and user interactions.

This configuration is ideal for teams, small businesses, and organizations that need a reliable project management solution with complete data ownership and customization capabilities. Unlike cloud-based alternatives, this setup provides full control over user data, attachment storage, and system behavior, making it particularly valuable for privacy-conscious organizations, development teams working on sensitive projects, or companies operating in regulated industries where data sovereignty is crucial.

## Features

- Real-time collaborative Kanban boards with drag-and-drop card management across customizable lists
- File attachment system with dedicated volume storage for project documents and images
- User avatar and project background image support with persistent storage volumes
- PostgreSQL database backend providing ACID compliance and reliable data integrity for project data
- Built-in user management with configurable admin accounts and team member permissions
- Card-based task management with support for due dates, labels, descriptions, and member assignments
- Project organization with multiple boards and customizable workflows per project
- Responsive web interface built with React for consistent experience across desktop and mobile devices

## Use cases

- Software development teams managing sprints, backlogs, and feature development workflows
- Marketing teams coordinating campaign planning, content creation, and approval processes
- Small business project management for client work, internal initiatives, and team coordination
- Educational institutions organizing coursework, research projects, and administrative tasks
- Remote teams requiring self-hosted collaboration tools with complete data control
- Organizations in regulated industries needing project management without external data sharing
- Personal productivity and household management for individuals preferring Kanban-style organization

## Prerequisites

- Docker and Docker Compose installed with container orchestration capabilities
- Minimum 512MB RAM for combined Planka application and PostgreSQL database operation
- Port 1337 available for Planka web interface access (configurable via PLANKA_PORT)
- Environment variables configured for database credentials, admin account, and secret key
- Sufficient disk space for PostgreSQL data, user avatars, project images, and file attachments
- Basic understanding of Kanban methodology and project management workflows

## docker-compose.yml

```yaml
services:
  planka:
    image: ghcr.io/plankanban/planka:latest
    container_name: planka
    restart: unless-stopped
    ports:
      - "${PLANKA_PORT:-1337}:1337"
    environment:
      - BASE_URL=http://localhost:${PLANKA_PORT:-1337}
      - DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@planka-db/planka
      - SECRET_KEY=${SECRET_KEY}
      - DEFAULT_ADMIN_EMAIL=${ADMIN_EMAIL}
      - DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - DEFAULT_ADMIN_NAME=Admin
      - DEFAULT_ADMIN_USERNAME=admin
    volumes:
      - planka_avatars:/app/public/user-avatars
      - planka_backgrounds:/app/public/project-background-images
      - planka_attachments:/app/private/attachments
    depends_on:
      - planka-db

  planka-db:
    image: postgres:15-alpine
    container_name: planka-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=planka
    volumes:
      - planka_db_data:/var/lib/postgresql/data

volumes:
  planka_avatars:
  planka_backgrounds:
  planka_attachments:
  planka_db_data:
```

## .env

```bash
# Planka
PLANKA_PORT=1337
DB_USER=planka
DB_PASSWORD=planka_password
SECRET_KEY=your_secret_key
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin_password
```

## Usage notes

- Planka at http://localhost:1337
- Login with admin credentials
- Create boards and projects
- Trello-like experience

## Troubleshooting

- Planka container fails to start: Verify DATABASE_URL environment variable format and ensure planka-db container is running and accessible
- Cannot login with admin credentials: Check DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD environment variables match your login attempt
- File attachments not saving: Ensure planka_attachments volume is properly mounted and container has write permissions to /app/private/attachments
- Database connection errors: Confirm PostgreSQL credentials (DB_USER, DB_PASSWORD) match between planka and planka-db service configurations
- Avatar or background images not displaying: Verify planka_avatars and planka_backgrounds volumes are mounted correctly and accessible
- Port 1337 already in use: Change PLANKA_PORT environment variable and update BASE_URL accordingly to use alternative port

