105 lines
5.5 KiB
Markdown
105 lines
5.5 KiB
Markdown
# Planka Kanban Board Playbook
|
|
|
|
## Overview
|
|
|
|
`planka.yml` deploys [Planka](https://planka.app), 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|