Vikunja — Self-Hosted Task Manager

Self-hosted task and project management at tasks.haiven.site. Vikunja 2.3.0 provides kanban boards, task lists, CalDAV sync, due-date reminders, and a full REST API — all from a single Go binary backed by dedicated PostgreSQL 17 and the shared Haiven Redis cache.

URLs

Quick Start

# Start
docker compose -f /mnt/apps/docker/vikunja/docker-compose.yml up -d

# Status
docker inspect vikunja --format='{{.State.Health.Status}}'
docker inspect vikunja-db --format='{{.State.Health.Status}}'

# Smoke test
curl -sf https://tasks.haiven.site/api/v1/info | python3 -m json.tool

# Logs
docker compose -f /mnt/apps/docker/vikunja/docker-compose.yml logs -f vikunja

Features

• Task management: lists, subtasks, due dates, assignees, labels, priorities, reminders
• Kanban boards: drag-and-drop, swimlanes, bucket limits
• Projects: hierarchical project/list organization with sharing
• CalDAV sync: tasks visible in DAVx5, Tasks.org, Apple Calendar (via token auth)
• REST API: 118 endpoints, full OpenAPI 3 spec at /api/v1/docs
• OIDC: Authentik SSO integration (login with sso.haiven.site)
• File attachments: task attachments stored in ./files/ (20 MB default limit)
• TOTP: two-factor authentication for local accounts
• Importers: Vikunja file, Todoist/TickTick CSV, Wekan

Architecture

flowchart TD
    Browser([Browser / Mobile]) -->|HTTPS 443| Traefik
    CalDAV([DAVx5 / Tasks.org]) -->|HTTPS /dav/| Traefik
    API([API clients]) -->|HTTPS /api/v1/| Traefik

    subgraph web["web network"]
        Traefik[Traefik\ntasks.haiven.site\nwildcard cert]
    end

    Traefik -->|HTTP 3456| Vikunja

    subgraph container["vikunja container"]
        V[Go backend + Vue frontend\nPort 3456]
        FV["./files\nUpload volume"]
        CV["config.yml\nread-only"]
        V --- FV
        V --- CV
    end

    subgraph backend["backend network"]
        DB[(vikunja-db\nPostgreSQL 17\n5432)]
        RD[(redis\nDB index 2\n6379)]
        SMTP[smtp-relay\n1025]
        AUTH[Authentik\nsso.haiven.site]
    end

    V -->|SQL| DB
    V -->|cache| RD
    V -->|SMTP| SMTP
    V -->|OIDC discovery| AUTH

Design notes:

• Unified image: vikunja/vikunja serves both Go backend and Vue frontend on port 3456 (the old vikunja/api + vikunja/frontend split was retired in v2.0.0).
• Traefik terminates TLS; no host port is published — container port 3456 is internal only.
• vikunja-db is on backend only (no host port). Redis is the shared redis container at DB index 2.
• Background tasks (reminders, email) run as goroutines inside the single container — no worker sidecar needed.
• The image is scratch-based (compiled Go binary + static assets). No shell, wget, or curl are available inside the container.

Configuration

Key env vars:

See .env.example for the full template with all options documented.

Backup and Restore

Database backup

docker exec vikunja-db pg_dump -U vikunja vikunja \
  | gzip > /mnt/storage/backups/vikunja/vikunja-$(date +%Y%m%d_%H%M%S).sql.gz

Files backup

rsync -avz /mnt/apps/docker/vikunja/files/ /mnt/storage/backups/vikunja/files/

Database restore

docker compose -f /mnt/apps/docker/vikunja/docker-compose.yml stop vikunja
docker exec -it vikunja-db psql -U vikunja -d postgres \
  -c "DROP DATABASE vikunja WITH (FORCE);"
docker exec -it vikunja-db psql -U vikunja -d postgres \
  -c "CREATE DATABASE vikunja OWNER vikunja;"
gunzip -c /mnt/storage/backups/vikunja/<timestamp>.sql.gz \
  | docker exec -i vikunja-db psql -U vikunja -d vikunja
docker compose -f /mnt/apps/docker/vikunja/docker-compose.yml start vikunja

Warning: Project deletion in Vikunja is permanent — no trash bin. Maintain daily backups.

Monitoring

Vikunja 2.3.0 does not expose a Prometheus /metrics endpoint. No built-in exporter exists at this version.

Current monitoring:

• Uptime Kuma HTTP monitor at https://tasks.haiven.site/api/v1/info (expected: HTTP 200, "version": "v2.3.0")
• Docker health check: docker inspect vikunja --format='{{.State.Health.Status}}'

TODO: Add a custom Blackbox Exporter probe or track the upstream Prometheus metrics issue for a future Vikunja release.

Upgrade

# Update image tag in docker-compose.yml, then:
docker compose -f /mnt/apps/docker/vikunja/docker-compose.yml pull
docker compose -f /mnt/apps/docker/vikunja/docker-compose.yml up -d
docker compose -f /mnt/apps/docker/vikunja/docker-compose.yml logs -f vikunja
# Watch for xormigrate migration lines — clean output = success

Troubleshooting

For detailed troubleshooting, see the full plan at /mnt/apps/docker/_server-setup/08/08l-vikunja-v2.md Section 15.

Key Paths

Related Documentation

• Full implementation plan: /mnt/apps/docker/_server-setup/08/08l-vikunja-v2.md
• Operator guide: /mnt/apps/docker/vikunja/USER_GUIDE.md
• Claude agent context: /mnt/apps/docker/vikunja/CLAUDE.md
• OpenAPI spec (live): https://tasks.haiven.site/api/v1/docs
• OpenAPI spec (static): /mnt/apps/docker/vikunja/openapi.json