Vikunja¶

Vikunja is the self-hosted project management tool used for task tracking and planning. It runs in the devops namespace alongside Jenkins, managed by Flux.

URL — pm.hdhomelab.com
Namespace — devops
Flux manifests — flux/apps/noah/devops/vikunja/
Database — PostgreSQL (192.168.68.4:5432)

Architecture¶

graph LR
    U[Browser] -->|pm.hdhomelab.com| GW[Gateway API\nshared]
    GW --> V[Vikunja\nport 3456]
    V --> PG[(PostgreSQL\nexternal)]
    V --> TS[Typesense\nfull-text search]
    V -->|OIDC login| AK[Authentik\nauth.hdhomelab.com]
    TS --> NFS[(NFS\nvikunja-typesense)]
    V --> NFS2[(NFS\nvikunja-data)]

Hold "Alt" / "Option" to enable pan & zoom

Deployment¶

Vikunja is installed from the official OCI Helm chart (ghcr.io/go-vikunja/helm-chart/vikunja, 1.*).

Setting	Value
Chart	`vikunja 1.*` (OCI)
Public URL	`https://pm.hdhomelab.com`
Timezone	`America/New_York`
Max items per page	`100`
Database	External PostgreSQL on `192.168.68.4:5432`
Cache	None (Redis disabled)
Full-text search	Typesense (sidecar)

Authentication¶

Login is handled by Authentik OIDC — the Vikunja application is registered at auth.hdhomelab.com/application/o/vikunja/.

OIDC setting	Value
Provider name	`Authentik`
Auth URL	`https://auth.hdhomelab.com/application/o/vikunja/`
Logout URL	`https://auth.hdhomelab.com/application/o/vikunja/end-session/`
Scope	`openid email profile`

Secrets¶

Secrets are pulled from Vault via ExternalSecrets into the vikunja-secret Kubernetes secret:

Key	Vault path	Purpose
`db-username`	`psql/vikunja`	PostgreSQL user
`db-password`	`psql/vikunja`	PostgreSQL password
`jwt-secret`	`vikunja/auth`	Session token signing
`typesense-api-key`	`vikunja/typesense`	Typesense auth
`oidc-client-id`	`vikunja/oidc`	Authentik client ID
`oidc-client-secret`	`vikunja/oidc`	Authentik client secret

Storage¶

Two NFS-backed PVCs on the Synology NAS (192.168.68.76):

PVC	NFS share	Size	Purpose
`vikunja-data`	`/volume2/homelab/k8s/pvc-vikunja-data`	2Gi	App data (attachments, avatars)
`vikunja-typesense`	`/volume2/homelab/k8s/pvc-vikunja-typesense`	1Gi	Typesense search index

Both use syno-nfs-retain with nfsvers=4.1. See Storage for storage class details.

Full-Text Search¶

Typesense runs as a sidecar within the same Helm release. Vikunja connects to it at http://vikunja-typesense:8108 and uses the shared API key from vikunja-secret. The search index is persisted to NFS so it survives pod restarts without a full re-index.

Networking¶

Traffic reaches Vikunja via a Gateway API HTTPRoute on the shared gateway (infra/shared):

pm.hdhomelab.com → shared gateway → vikunja:3456

The Helm chart's built-in Ingress is disabled (ingress.main.enabled: false) in favour of the HTTPRoute. See Networking for gateway details.