37 lines
1.9 KiB
Markdown
37 lines
1.9 KiB
Markdown
|
---
|
||
|
|
summary: "Planka v2.1.1 API and Docker behaviors that differ from or are absent in its docs — auth/PAT limits, first-login terms flow, card-move and project-delete quirks, container uid."
|
||
|
|
tags:
|
||
|
|
- type/reference
|
||
|
|
- tool/planka
|
||
|
|
- project/backlog-pilot
|
||
|
|
- domain/self-hosting
|
||
|
|
scope: global
|
||
|
|
source: ovh-prod Planka deploy, 2026-07-08
|
||
|
|
date: 2026-07-08
|
||
|
|
last_updated: 2026-07-08
|
||
|
|
---
|
||
|
|
|
||
|
|
# Planka v2 API Gotchas (verified on v2.1.1)
|
||
|
|
|
||
|
|
Discovered during the ovh-prod deploy (2026-07-08), verified against a live v2.1.1 instance.
|
||
|
|
Directly relevant to the `backlog` CLI in `~/dev/ruby-gems` and any Planka automation.
|
||
|
|
|
||
|
|
1. **No scoped API keys / PATs.** Only `POST /api/access-tokens` with
|
||
|
|
`{emailOrUsername, password}` → bearer JWT. Upstream issue
|
||
|
|
[#945](https://github.com/plankanban/planka/issues/945) still open as of v2.1.1.
|
||
|
|
Automation must hold real user credentials; a scoped-token proxy is the workaround.
|
||
|
|
2. **First-ever login requires terms acceptance.** The first `POST /api/access-tokens`
|
||
|
|
returns `E_FORBIDDEN` with a `pendingToken` and `step: "accept-terms"`. Flow:
|
||
|
|
`GET /api/terms` → take `item.signature` → `POST /api/access-tokens/accept-terms`
|
||
|
|
with `{pendingToken, signature}` → real token. Subsequent logins are normal.
|
||
|
|
3. **Card move needs both fields.** `PATCH /api/cards/:id` requires **both** `listId`
|
||
|
|
and `position`; `listId` alone returns `E_MISSING_OR_INVALID_PARAMS`.
|
||
|
|
4. **Project delete is not cascading.** `DELETE /api/projects/:id` returns 422
|
||
|
|
`"Must not have boards"` — delete each board first.
|
||
|
|
5. **Container uid.** The `ghcr.io/plankanban/planka` image runs as uid 1000 (`node`).
|
||
|
|
A bind-mounted `/app/data` must be `chown 1000` or attachment/avatar uploads fail
|
||
|
|
(container starts healthy either way — the failure is silent until first upload).
|
||
|
|
|
||
|
|
Deploy as-built details live in the repo: `ovh-prod/docs/planka-deploy-prd.md`.
|
||
|
|
Related: [[vault-backlog-pilot-plan]], [[backlog-system-options-research]].
|