Zum Inhalt

Self-Hosting Project Management: Vikunja on Debian Linux (Go Backend, Kanban, Gantt & CalDAV)

Executive Summary: Legacy self-hosted Kanban tools (Kanboard, Wekan) suffer from either dated 2010s PHP interfaces or heavyweight MongoDB dependencies. Vikunja is the modern open-source standard for personal and team project management—combining a single-binary Go API + Vue 3 SPA with four interchangeable project views (List, Kanban Board, Gantt Timeline, and Table), Todoist-style Quick-Add Magic Syntax (*label +project @assignee tomorrow), and native CalDAV synchronization with mobile task apps.

  • 4 Views on One Data Model

    Switch any project seamlessly between Todo List, Kanban Board (with WIP limits), Gantt Chart, and Spreadsheet Table.

  • Quick-Add Magic Syntax

    Type Deploy Kernel Patch *urgent @nejat !3 tomorrow 09:00 to assign labels, priority, user, and due dates in a single keystroke.

  • Native CalDAV & API Tokens

    Sync tasks natively to Android (Tasks.org / DAVx⁵), iOS Reminders, and Thunderbird via built-in CalDAV endpoints.

  • Single Unified Container

    Since Vikunja v0.21+, the Go backend and Vue 3 frontend ship inside a single unified container requiring < 45 MB of RAM.

1. Vikunja Unified Architecture

In older tutorials (pre-0.21), Vikunja required deploying separate api and frontend containers connected via an internal Nginx proxy. Modern Vikunja embeds the compiled Vue 3 frontend directly into the Go binary on port 3456:

%%{init: {'flowchart': {'wrappingWidth': 600}}}%%
flowchart TB
    CLI["🌐 Web Browser (Vue 3 SPA)<br/>& CalDAV Mobile Clients"]
    PROXY["🔒 Reverse Proxy (TLS 1.3)<br/>tasks.nejat-hakan.de"]
    VIK["🚀 Vikunja Unified Binary (Go)<br/>127.0.0.1:3456<br/>(REST API + CalDAV + Static UI)"]
    PG["🗄️ PostgreSQL 17<br/>Tasks, Kanban Buckets & ACLs"]

    CLI <--> PROXY
    PROXY <--> VIK
    VIK <--> PG

2. Production compose.yaml (Vikunja + PostgreSQL 17)

Prepare the local attachment directory with UID 1000 ownership (Vikunja runs rootless as UID 1000 inside its container by default!) and deploy with PostgreSQL 17:

# File: /opt/vikunja-ops/01_prepare_dirs.sh
sudo mkdir -p /srv/containers/vikunja/{files,postgres}
sudo chown -R 1000:1000 /srv/containers/vikunja/files

# File: /srv/containers/vikunja/compose.yaml
services:
  vikunja:
    image: docker.io/vikunja/vikunja:latest
    container_name: vikunja
    depends_on:
      vikunja-db:
        condition: service_healthy
    restart: unless-stopped
    ports:
      - "127.0.0.1:3456:3456/tcp"
    environment:
      VIKUNJA_SERVICE_PUBLICURL: "https://tasks.nejat-hakan.de/"
      VIKUNJA_SERVICE_TIMEZONE: "Europe/Berlin"
      # Lock open registration after creating your admin/team accounts!
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
      VIKUNJA_SERVICE_JWTTTL: "2592000"
      # Database connection
      VIKUNJA_DATABASE_TYPE: "postgres"
      VIKUNJA_DATABASE_HOST: "vikunja-db"
      VIKUNJA_DATABASE_USER: "vikunja"
      VIKUNJA_DATABASE_PASSWORD: "${VIKUNJA_DB_PASSWORD}"
      VIKUNJA_DATABASE_DATABASE: "vikunja"
    volumes:
      - /srv/containers/vikunja/files:/app/vikunja/files:rw

  vikunja-db:
    image: docker.io/library/postgres:17-bookworm
    container_name: vikunja-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: "vikunja"
      POSTGRES_PASSWORD: "${VIKUNJA_DB_PASSWORD}"
      POSTGRES_DB: "vikunja"
    volumes:
      - /srv/containers/vikunja/postgres:/var/lib/postgresql/data:rw
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U vikunja -d vikunja"]
      interval: 10s
      timeout: 5s
      retries: 5

3. CLI User Provisioning (With Public Registration Disabled)

Because we set VIKUNJA_SERVICE_ENABLEREGISTRATION: "false" so random internet visitors cannot sign up on your task server, create user accounts cleanly via the built-in vikunja user create CLI:

# File: /opt/vikunja-ops/02_create_admin_user.sh
docker exec -it vikunja /app/vikunja/vikunja user create \
    --username nejat \
    --email nejat.hakan@googlemail.com \
    --password "Strong_Initial_Password_2026!"

Where to Go Next

Integrate Vikunja into your broader engineering and collaboration platform:

  • Joplin E2EE Note Server

    Link Vikunja engineering tasks directly to encrypted technical architecture notes in Joplin.

    Joplin Guide

  • Forgejo Self-Hosted Git Server

    Manage source code repositories, pull requests, and CI/CD pipelines alongside your project boards.

    Forgejo Guide

  • Mattermost Team Chat

    Send automated Vikunja webhook notifications into your self-hosted DevOps team chat channels.

    Mattermost Guide