stack.basicstack.de/apps/vikunja/README.md

# Vikunja (vikunja.basicstack.de)

Self-hosted task manager. Unified `vikunja/vikunja` container (API + frontend on port 3456). Backed by a namespace-local PostgreSQL. OIDC via Pocket ID (`auth.basicstack.de`); local login disabled.

## Layout

| File | Purpose |
|---|---|
| `vikunja-db-pvc.yaml` | 10 Gi encrypted PVC for Postgres data |
| `vikunja-files-pvc.yaml` | 10 Gi encrypted PVC for user-uploaded attachments (`/app/vikunja/files`) |
| `vikunja-postgres-deployment.yaml` | Postgres 16, pinned to `csi.hetzner.cloud/location=fsn1` |
| `vikunja-postgres-service.yaml` | ClusterIP `vikunja-postgres:5432` |
| `vikunja-deployment.yaml` | Vikunja app, pinned to `fsn1`, waits on Postgres |
| `vikunja-service.yaml` | ClusterIP `vikunja:80` → pod `3456` |
| `vikunja-ingress.yaml` | Traefik + `letsencrypt-prod` cert |
| `vikunja-db-credentials-sealed.yaml` | Postgres user password |
| `vikunja-oidc-secret-sealed.yaml` | Pocket ID client id + secret |
| `vikunja-app-secrets-sealed.yaml` | Vikunja JWT secret |

## Node placement

Both the app and Postgres pin to Hetzner location `fsn1` because their PVCs live on `hcloud-volumes-encrypted` (datacenter-local).

## OIDC

- Pocket ID client `Vikunja` (id `cdfff4ee-28ba-4aab-9f47-7e41b4b6b847`), callback `https://vikunja.basicstack.de/auth/openid/basicstack`.
- Pocket ID groups `vikunja_admins` and `vikunja_members`.
- Vikunja does not map OIDC groups to the admin flag. Promote the first user post-login: `kubectl -n vikunja exec deploy/vikunja -- /app/vikunja/vikunja user set-admin --admin <username>`.
- **PKCE must be OFF on the Pocket ID client.** Vikunja 2.x's OAuth redirect (`frontend/src/helpers/redirectToProvider.ts`) does not send `code_challenge`, and the Go backend does not implement PKCE either. With `pkceEnabled: true` on Pocket ID the flow fails at `/authorize` with `invalid_request … 'code_challenge' parameter is missing`. Client is confidential (`isPublic: false`), so `client_secret` still authenticates the token exchange.

## Optional: SMTP

`VIKUNJA_MAILER_ENABLED=false` today. To enable reminder emails, create a Stalwart mailbox `vikunja@basicstack.de`, add its credentials as a sealed secret `vikunja-mailer`, and set `VIKUNJA_MAILER_ENABLED=true` plus host/port/from env vars.

## Change control

Manifest changes flow through Argo CD (Application: `apps/app-vikunja.yaml`, auto-sync + prune + selfHeal). Sealed secrets are encrypted against the cluster-active sealed-secrets key.
feat(vikunja): deploy Vikunja 2.6.0 with Pocket ID OIDC (DEV-560) Namespace-scoped Postgres 16 + unified Vikunja container behind Traefik ingress at vikunja.basicstack.de. Both pods pinned to Hetzner fsn1 due to their encrypted PVCs (10 Gi DB, 10 Gi attachments). Local auth disabled; sign-in only via Pocket ID (client `Vikunja`, groups `vikunja_admins` / `vikunja_members`). SMTP mailer left disabled pending mailbox provisioning. Co-Authored-By: Paperclip <noreply@paperclip.ing> 2026-09-05 09:38:25 +00:00			`# Vikunja (vikunja.basicstack.de)`

			Self-hosted task manager. Unified `vikunja/vikunja` container (API + frontend on port 3456). Backed by a namespace-local PostgreSQL. OIDC via Pocket ID (`auth.basicstack.de`); local login disabled.

			`## Layout`

			`\| File \| Purpose \|`
			`\|---\|---\|`
			\| `vikunja-db-pvc.yaml` \| 10 Gi encrypted PVC for Postgres data \|
			\| `vikunja-files-pvc.yaml` \| 10 Gi encrypted PVC for user-uploaded attachments (`/app/vikunja/files`) \|
			\| `vikunja-postgres-deployment.yaml` \| Postgres 16, pinned to `csi.hetzner.cloud/location=fsn1` \|
			\| `vikunja-postgres-service.yaml` \| ClusterIP `vikunja-postgres:5432` \|
			\| `vikunja-deployment.yaml` \| Vikunja app, pinned to `fsn1`, waits on Postgres \|
			\| `vikunja-service.yaml` \| ClusterIP `vikunja:80` → pod `3456` \|
			\| `vikunja-ingress.yaml` \| Traefik + `letsencrypt-prod` cert \|
			\| `vikunja-db-credentials-sealed.yaml` \| Postgres user password \|
			\| `vikunja-oidc-secret-sealed.yaml` \| Pocket ID client id + secret \|
			\| `vikunja-app-secrets-sealed.yaml` \| Vikunja JWT secret \|

			`## Node placement`

			Both the app and Postgres pin to Hetzner location `fsn1` because their PVCs live on `hcloud-volumes-encrypted` (datacenter-local).

			`## OIDC`

			- Pocket ID client `Vikunja` (id `cdfff4ee-28ba-4aab-9f47-7e41b4b6b847`), callback `https://vikunja.basicstack.de/auth/openid/basicstack`.
			- Pocket ID groups `vikunja_admins` and `vikunja_members`.
chore(vikunja): rename JWT env to non-deprecated service.secret (DEV-560) Vikunja 2.6.0 deprecates `service.jwtsecret` in favor of `service.secret`; switch the env var name (secret payload unchanged) and fix the admin-promotion example in the README to the current CLI (`user set-admin --admin`). Co-Authored-By: Paperclip <noreply@paperclip.ing> 2026-09-05 09:41:05 +00:00			- Vikunja does not map OIDC groups to the admin flag. Promote the first user post-login: `kubectl -n vikunja exec deploy/vikunja -- /app/vikunja/vikunja user set-admin --admin <username>`.
docs(vikunja): note PKCE must be off on Pocket ID client (DEV-560) Vikunja 2.x's frontend redirect helper and Go backend do not send code_challenge. Pocket ID rejects the /authorize call with 'code_challenge parameter is missing' when the client has pkceEnabled=true. The Vikunja client is confidential (isPublic=false) so client_secret still authenticates the token exchange — turning PKCE off is safe and required. Co-Authored-By: Paperclip <noreply@paperclip.ing> 2026-09-05 09:56:07 +00:00			- PKCE must be OFF on the Pocket ID client. Vikunja 2.x's OAuth redirect (`frontend/src/helpers/redirectToProvider.ts`) does not send `code_challenge`, and the Go backend does not implement PKCE either. With `pkceEnabled: true` on Pocket ID the flow fails at `/authorize` with `invalid_request … 'code_challenge' parameter is missing`. Client is confidential (`isPublic: false`), so `client_secret` still authenticates the token exchange.
feat(vikunja): deploy Vikunja 2.6.0 with Pocket ID OIDC (DEV-560) Namespace-scoped Postgres 16 + unified Vikunja container behind Traefik ingress at vikunja.basicstack.de. Both pods pinned to Hetzner fsn1 due to their encrypted PVCs (10 Gi DB, 10 Gi attachments). Local auth disabled; sign-in only via Pocket ID (client `Vikunja`, groups `vikunja_admins` / `vikunja_members`). SMTP mailer left disabled pending mailbox provisioning. Co-Authored-By: Paperclip <noreply@paperclip.ing> 2026-09-05 09:38:25 +00:00
			`## Optional: SMTP`

			`VIKUNJA_MAILER_ENABLED=false` today. To enable reminder emails, create a Stalwart mailbox `vikunja@basicstack.de`, add its credentials as a sealed secret `vikunja-mailer`, and set `VIKUNJA_MAILER_ENABLED=true` plus host/port/from env vars.

			`## Change control`

			Manifest changes flow through Argo CD (Application: `apps/app-vikunja.yaml`, auto-sync + prune + selfHeal). Sealed secrets are encrypted against the cluster-active sealed-secrets key.