How to install Planka

How to self-host planka. Trello alternative

Theory

What is Planka?

Planka is an open-source project management tool inspired by Trello, built for organizing tasks and team collaboration using Kanban boards. It allows you to self-host and maintain full control over your projects without depending on proprietary cloud services. With features like boards, lists, cards, labels, due dates, and real-time collaboration, Planka provides a simple yet powerful platform for managing workflows, whether for personal productivity or team-based projects.

What is docker

Docker is an open-source platform that makes it easy to build, package, and run applications in lightweight, portable containers. A container is like a mini virtual environment that bundles together an application with all its dependencies (libraries, configurations, runtime, etc.) so it runs the same way on any machine. Unlike traditional virtual machines, containers don’t need a full operating system — they share the host’s kernel — which makes them much faster and more efficient. Developers use Docker to avoid the classic “it works on my machine” problem, because containers ensure consistency across development, testing, and production environments. It’s widely used for microservices, cloud deployments, and modern DevOps workflows.

---

Hands on!

Planka Setup Guide - Working Configuration

This guide provides the exact commands to set up Planka successfully without conflicts.

This is a summary of the docs.

🚀 Initial Setup

1. Create Directory Structure

# Create directory for Planka
sudo mkdir -p /opt/planka
cd /opt/planka

2. Download docker-compose.yml

# Create the configuration file
curl -L https://raw.githubusercontent.com/plankanban/planka/master/docker-compose.yml -o /opt/planka/docker-compose.yml

Content for docker-compose.yml:

(Because of the planka updates, it may look different)

services:
  planka:
    image: ghcr.io/plankanban/planka:2.0.0-rc.3
    restart: on-failure
    volumes:
      - favicons:/app/public/favicons
      - user-avatars:/app/public/user-avatars
      - background-images:/app/public/background-images
      - attachments:/app/private/attachments
    ports:
      - 3001:1337  # Use 3001 to avoid conflicts with other web services
    environment:
      - BASE_URL=http://localhost:3001
      - DATABASE_URL=postgresql://postgres@postgres/planka
      - SECRET_KEY=SOME_LONG_SECRET_KEY
      
      # Optional: Configure default admin user
      - DEFAULT_ADMIN_EMAIL=[e-mail]
      - DEFAULT_ADMIN_PASSWORD=planka123
      - DEFAULT_ADMIN_NAME=Planka Admin
      - DEFAULT_ADMIN_USERNAME=admin
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    restart: on-failure
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=planka
      - POSTGRES_HOST_AUTH_METHOD=trust
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d planka"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  favicons:
  user-avatars:
  background-images:
  attachments:
  db-data:

🐳 Deployment Commands

3. Start Planka

# Start all services
sudo docker compose up -d

# Check status
docker ps

# Check logs
docker logs planka-planka-1 --tail=20

4. Wait for Services to be Ready

# Wait for database to be healthy (usually 30-60 seconds)
docker ps --format "table {{.Names}}\t{{.Status}}"

# Should show both containers as healthy

🔐 Access and Login

5. Access Planka

• URL: http://localhost:3001

• Admin Email: [e-mail]

• Admin Password: planka123

6. Verify WebSocket Connection

• Open browser developer tools (F12)

• Go to Network tab

• Look for WebSocket connections

• Should see successful WebSocket connections without errors

🔧 Troubleshooting Commands

Check Service Health

# View all running containers
docker ps --format "table {{.Names}}\t{{.Ports}}\t{{.Status}}"

# Check specific service logs
docker logs planka-planka-1 --tail=50
docker logs planka-postgres-1 --tail=50

Restart Services

# Restart specific service
docker restart planka-planka-1

# Restart all services
cd /opt/planka
sudo docker compose restart

# Full restart with fresh containers
sudo docker compose down && sudo docker compose up -d

Database Access (If Needed)

# Access PostgreSQL database
docker exec -it planka-postgres-1 psql -U postgres -d planka

# List tables
\dt

# Exit database
\q

🚨 Common Issues and Solutions

Issue 1: Port Conflicts

Symptoms:

• "Port already in use" errors

• Cannot start services

Solution:

# Check what's using the port
netstat -tulpn | grep :3001
lsof -i :3001

# Kill processes if needed or change port in docker-compose.yml

Issue 2: Permission Denied

Symptoms:

• Cannot edit docker-compose.yml

• Cannot start services

Solution:

# Use sudo for file operations in /opt/
sudo vim /opt/planka/docker-compose.yml
sudo docker compose up -d

Issue 3: Database Connection Issues

Symptoms:

• Planka shows "Database connection failed"

• Container keeps restarting

Solution:

# Check database status
docker logs planka-postgres-1

# Restart database first, then app
docker restart planka-postgres-1
sleep 10
docker restart planka-planka-1

Issue 4: WebSocket Connection Failed

Symptoms:

• Real-time updates not working

• JavaScript console errors

Solution:

# Ensure no other services are using port 80 or 443
docker ps | grep "80\|443"

# Restart with clean state
cd /opt/planka
sudo docker compose down
sudo docker compose up -d

📋 Maintenance Commands

Backup Database

# Create backup
docker exec planka-postgres-1 pg_dump -U postgres planka > planka_backup_$(date +%Y%m%d).sql

Update Planka

cd /opt/planka

# Pull latest images
sudo docker compose pull

# Restart with new images
sudo docker compose up -d

Clean Unused Resources

# Remove unused images
docker image prune -f

# Remove unused volumes
docker volume prune -f

# Full system cleanup
docker system prune -f

🔍 Verification Checklist

After setup, verify these items:

• Planka accessible at http://localhost:3001

• Can login with admin credentials

• Can create boards/projects

• Real-time updates work (no WebSocket errors in console)

• Database persists data after container restart

• No port conflicts with other services

📝 Configuration Summary

Component	Port	URL
Planka Web	3001	http://localhost:3001
PostgreSQL	5432	Internal only

Default Credentials
Admin Email	[e-mail]
Admin Password	planka123

🔗 Related Services

If running other services, ensure no port conflicts:

Service	Ports Used	Notes
Planka	3001	Main application
n8n	5678	Automation