Planka Runbook

Last Verified: 2026-02-17 | Owner: John 
 
 Runbook: Planka 
 Service Type: Kanban Board / Project Management
 Container: planka (ghcr.io/plankanban/planka:2.0.0-rc.4)
 Ports: 3100 (external) → 1337 (internal)
 External URL: https://boards.basicconsulting.no
 Database: PostgreSQL 15 (planka-db)
 Compose File: ~/system/services/planka/docker-compose.yml 
 
 Service Info 
 Planka is the visual project management tool for BasicAS Group. Kanban-style boards for task tracking. 
 Stack: 
 
 planka - Main app (RC4) 
 planka-db - PostgreSQL 15 (alpine) 
 
 External Access: 
 
 Exposed via Cloudflare Tunnel: boards.basicconsulting.no 
 Trust proxy enabled for correct client IPs 
 
 Admin Access: 
 
 Web UI: http://localhost:3100 (local) or https://boards.basicconsulting.no 
 Username: john 
 Password: BasicAS2026! 
 Email: john@basicconsulting.no 
 Database: postgresql://postgres@planka-db/planka (internal only, no auth) 
 
 
 Status Check 
 Container Health 
 docker ps | grep planka
 
 Expected output: 
 planka Up X hours (healthy)
planka-db Up X hours (healthy)
 
 HTTP Check 
 curl -I http://localhost:3100
 
 Expected: 200 OK or 302 Found 
 External Access Check 
 curl -I https://boards.basicconsulting.no
 
 Expected: 200 OK or 302 Found 
 Database Check 
 docker exec planka-db psql -U postgres -d planka -c "SELECT count(*) FROM \"user\";"
 
 
 Restart Procedure 
 Quick Restart (Container Only) 
 docker restart planka
 
 Full Stack Restart (Container + Database) 
 cd ~/system/services/planka
docker compose down
docker compose up -d
 
 Wait 30 seconds for healthcheck to pass, then verify: 
 docker ps | grep planka
curl -I http://localhost:3100
 
 
 Troubleshooting 
 Problem: Container won't start 
 Check logs: 
 docker logs planka --tail 100
 
 Common causes: 
 
 Database not ready - wait 30s and retry 
 Port 3100 already bound - check lsof -i :3100 
 Volume permission issues - check docker volumes 
 
 Fix: 
 cd ~/system/services/planka
docker compose down
docker compose up -d planka-db
sleep 30
docker compose up -d planka
 
 Problem: Login issues (can't sign in with admin credentials) 
 Check environment variables: 
 docker exec planka env | grep DEFAULT_ADMIN
 
 Expected: 
 DEFAULT_ADMIN_EMAIL=john@basicconsulting.no
DEFAULT_ADMIN_PASSWORD=BasicAS2026!
DEFAULT_ADMIN_NAME=John AI
DEFAULT_ADMIN_USERNAME=john
 
 If admin was changed in UI, default credentials won't work. Reset via database: 
 docker exec planka-db psql -U postgres -d planka -c "SELECT email, username FROM \"user\" WHERE \"isAdmin\" = true;"
 
 Problem: 502 Bad Gateway (external access) 
 Check container is running: 
 docker ps | grep planka
 
 Check Cloudflare tunnel: 
 cloudflared tunnel info boards
 
 Check BASE_URL: 
 docker exec planka env | grep BASE_URL
 
 Expected: BASE_URL=https://boards.basicconsulting.no 
 Problem: Database connection issues 
 Check database health: 
 docker exec planka-db pg_isready -U postgres -d planka
 
 Check connection string: 
 docker exec planka env | grep DATABASE_URL
 
 Expected: DATABASE_URL=postgresql://postgres@planka-db/planka 
 
 API Access 
 Planka has a REST API. Example: 
 Get Boards (requires auth token) 
 curl -H "Authorization: Bearer <TOKEN>" http://localhost:3100/api/boards
 
 Get Token: 
 
 Login via UI 
 Inspect browser Network tab → find accessToken in response 
 Or use user credentials to authenticate programmatically 
 
 
 Dependencies 
 
 Docker - Service runtime 
 Cloudflare Tunnel - External access (boards.basicconsulting.no) 
 
 No dependencies on other local services. 
 
 Backup 
 Database Dump 
 docker exec planka-db pg_dump -U postgres planka | gzip > ~/backups/planka-$(date +%Y%m%d-%H%M%S).sql.gz
 
 Docker Volumes (includes file uploads) 
 docker run --rm -v planka-data:/data -v ~/backups:/backup alpine tar -czf /backup/planka-data-$(date +%Y%m%d-%H%M%S).tar.gz -C /data .
docker run --rm -v planka-db-data:/data -v ~/backups:/backup alpine tar -czf /backup/planka-db-data-$(date +%Y%m%d-%H%M%S).tar.gz -C /data .
 
 Restore from Backup 
 # Stop service
cd ~/system/services/planka
docker compose down

# Restore database
gunzip -c ~/backups/planka-YYYYMMDD-HHMMSS.sql.gz | docker exec -i planka-db psql -U postgres -d planka

# Restore volumes (if needed)
docker run --rm -v planka-data:/data -v ~/backups:/backup alpine tar -xzf /backup/planka-data-YYYYMMDD-HHMMSS.tar.gz -C /data
docker run --rm -v planka-db-data:/data -v ~/backups:/backup alpine tar -xzf /backup/planka-db-data-YYYYMMDD-HHMMSS.tar.gz -C /data

# Start service
docker compose up -d
 
 
 Configuration 
 Key Environment Variables 
 
 BASE_URL - External URL (https://boards.basicconsulting.no) 
 DATABASE_URL - PostgreSQL connection string 
 SECRET_KEY - Encryption key for sessions/tokens 
 TOKEN_EXPIRES_IN - JWT token expiry (365 days) 
 DEFAULT_LANGUAGE - UI language (en-US) 
 DEFAULT_ADMIN_* - Initial admin user credentials 
 TRUST_PROXY - Enable for correct IPs behind Cloudflare 
 
 Full config: ~/system/services/planka/docker-compose.yml 
 
 Notes 
 
 Version: 2.0.0-rc.4 (release candidate, not stable) 
 Auth method: Password-based (no SSO/LDAP yet) 
 Database: Uses PostgreSQL with trust auth (no password) - secure as internal-only 
 Token expiry: 365 days (1 year) - very long, consider shorter for security 
 Admin password: Stored in docker-compose.yml (plaintext) - consider secrets management 
 
 
 Last updated: 2026-02-10
 Maintained by: John (AI Director)