Productivity, checked 2026-09-07
Vikunja: Docker configuration reference
Self-hosted task and project management with lists, Kanban, Gantt charts and a CalDAV endpoint.
At a glance
Ports
Ports| Port | What listens | Source |
|---|
3456 | HTTP listener for both the API and the bundled frontend, served from a single container since the API, frontend and desktop repos were merged in v0.23.0. | source for port 3456 |
Environment variables
Environment variables| Variable | Required | What it does | Example | Source |
|---|
VIKUNJA_SERVICE_PUBLICURL | Yes | Public URL Vikunja is reachable on, trailing slash included. Used to build links in emails and the frontend's API calls. | https://tasks.example.com/ | source for VIKUNJA_SERVICE_PUBLICURL |
VIKUNJA_SERVICE_SECRET | Yes | Secret used to sign JWT auth tokens. Must be set explicitly; changing it later invalidates every existing session. | a long random string | source for VIKUNJA_SERVICE_SECRET |
VIKUNJA_DATABASE_TYPE | Yes | Database backend: postgres, mysql or sqlite. The documented compose examples default to postgres. | postgres | source for VIKUNJA_DATABASE_TYPE |
VIKUNJA_DATABASE_HOST | No | Database hostname, required when VIKUNJA_DATABASE_TYPE is postgres or mysql rather than sqlite. | db | source for VIKUNJA_DATABASE_HOST |
Volumes that must persist
Volumes| Path | What is in it | Source |
|---|
/app/vikunja/files | Task attachments and uploaded files. Vikunja runs as uid 1000 and needs this directory writable by that user, or as root under rootless Docker. | source for /app/vikunja/files |
/var/lib/postgresql (db) | Postgres data directory in the documented compose example, holding every project, task and user. | source for /var/lib/postgresql |
Behind a reverse proxy
- Route the domain to container port 3456. Since v0.23.0 this single container serves both the API and the frontend, unlike older guides that proxy two separate containers. source for this reverse-proxy note
- Set VIKUNJA_SERVICE_PUBLICURL to the externally reachable address with a trailing slash, not the container's internal port 3456. source for this reverse-proxy note
- Vikunja config is file or environment, with nested config.yml keys mapping to a VIKUNJA_ prefixed, underscore-joined variable, and the environment variable always wins over the file. source for this reverse-proxy note
- The documented NGINX Proxy Manager setup toggles Websockets Support and sets a raised client_max_body_size on plain NGINX to match Vikunja's own upload size setting. source for this reverse-proxy note
What it needs alongside it
Dependencies| Dependency | Why | Source |
|---|
| PostgreSQL, MySQL, MariaDB or SQLite | Application database. The documented walkthrough pairs Vikunja with postgres:18; MySQL and MariaDB need explicit utf8mb4 configuration for non-Latin characters. | source for PostgreSQL, MySQL, MariaDB or SQLite |
Release timeline
Releases| Version | Date | Breaking | What changed | Source |
|---|
v2.6.0 | 2026-08-31 | No | 380 commits including 18 security fixes, plus importing from Planka and previews for image, audio and video attachments. | source for release v2.6.0 |
v2.5.0 | 2026-08-04 | No | Fixes a share link that could act as another user, and batches quick add magic pastes into one request. | source for release v2.5.0 |
v2.4.0 | 2026-07-19 | No | Ten security fixes, the first Vikunja Pro features, and a new v2 API. | source for release v2.4.0 |
v2.3.0 | 2026-04-09 | No | Eleven security fixes, a new plugin system, and support for Vikunja acting as an OAuth 2.0 provider. | source for release v2.3.0 |
v2.2.2 | 2026-03-23 | No | Nine security fixes including a critical chain that could expose instance-wide data, plus centralised SSRF protection. | source for release v2.2.2 |
If it is not coming up
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.
Other app references
All app references