wulf-ansible/playbooks/planka.md

Planka Kanban Board Playbook

Overview

planka.yml deploys Planka, a self-hosted kanban board application. The playbook provisions a Postgres database and the Planka app container via Docker Compose, generates and persists cryptographic secrets, and registers the stack on the pangolin overlay network for reverse-proxy access.

Architecture

┌─────────────────────────────────┐         ┌──────────────────────────┐
│  Target Docker Host             │         │  Pangolin Server         │
│                                 │         │  pangolin.wulfconsulting  │
│  ┌─────────────┐  planka_net    │         │  .cloud                  │
│  │ planka_app  │◀──────────────▶│         │                          │
│  │ (planka)    │  :3000→1337    │ pangolin│  Routes traffic to       │
│  └──────┬──────┘  network  ─────────────▶│  planka.<domain>         │
│         │                       │         └──────────────────────────┘
│  ┌──────▼──────┐                │
│  │ planka-     │                │
│  │ postgres    │                │
│  │ (pg 16)     │                │
│  └─────────────┘                │
│                                 │
│  /opt/stacks/planka/            │
│  ├── compose.yaml               │
│  └── .secrets  (mode 0600)      │
└─────────────────────────────────┘

Playbook structure

Section	Purpose
vars	Sets stack directory, Planka version, port, base URL, admin credentials, and secret-rotation flag
pre_tasks	Validates admin password is not default, checks planka_base_url is set, verifies Docker is running, ensures pangolin Docker network exists
tasks	Creates stack directory, generates/persists/reads cryptographic secrets, renders compose.yaml, deploys via docker_compose_v2, health-checks the HTTP endpoint, prints a deployment summary
handlers	Restarts the Planka stack when compose.yaml changes

Secrets (SECRET_KEY and INTERNAL_ACCESS_TOKEN) are generated on first run and stored in /opt/stacks/planka/.secrets (root-only, mode 0600). Subsequent runs re-use the persisted values unless planka_rotate_secrets: true is passed.

Usage

Required extra vars

Variable	Description
planka_admin_password	Admin account password — must not be the default ChangeMe123!
planka_base_url	Public URL Planka will be accessed at (used in auth cookies and links)

Optional extra vars

Variable	Default	Description
planka_version	2.0.0-rc.3	Planka image tag
planka_port	3000	Host port mapped to the Planka container
planka_trust_proxy	false	Set true when behind a reverse proxy (enables real-IP headers)
planka_token_expires_in	365	Session token lifetime in days
planka_log_level	warn	Planka log verbosity (debug, info, warn, error)
planka_db_name	planka	Postgres database name
planka_admin_email	admin@example.com	Admin account e-mail
planka_admin_name	Planka Admin	Admin display name
planka_admin_username	admin	Admin username
planka_rotate_secrets	false	Set true to force regeneration of SECRET_KEY and INTERNAL_ACCESS_TOKEN

Deploy to a host

ansible-playbook playbooks/planka.yml --limit myhost \
  -e planka_admin_password=SuperSecret99! \
  -e planka_base_url=https://planka.wulfconsulting.cloud

Override image version and port

ansible-playbook playbooks/planka.yml --limit myhost \
  -e planka_admin_password=SuperSecret99! \
  -e planka_base_url=https://planka.wulfconsulting.cloud \
  -e planka_version=latest \
  -e planka_port=3001

Rotate secrets on an existing deployment

ansible-playbook playbooks/planka.yml --limit myhost \
  -e planka_admin_password=SuperSecret99! \
  -e planka_base_url=https://planka.wulfconsulting.cloud \
  -e planka_rotate_secrets=true

Verify the containers are running

ansible myhost -a "docker ps --filter name=planka"

Notes

• planka_base_url is required. Planka embeds this URL in auth tokens and e-mail links; an incorrect value will break logins from behind a proxy.
• planka_trust_proxy: true is needed behind Pangolin/Traefik. Without it, Planka sees the proxy's IP instead of the real client IP.
• Admin credentials are first-run only. DEFAULT_ADMIN_* env vars only take effect when Planka initialises a fresh database. Changing them after the first deploy has no effect; use the Planka UI instead.
• Secrets are host-side persistent. /opt/stacks/planka/.secrets survives container re-creation. Use planka_rotate_secrets=true only when intentionally invalidating all active sessions.
• --limit is required. The playbook targets all hosts; always scope it to the intended host.
• Postgres data is in a named Docker volume (db-data). Destroying the stack with docker compose down -v will wipe the database.