Skip to main content

Vikunja

Purpose

Vikunja provides project and task management for the two-person video game project.

The service is used for:

    Project planning. Kanban boards. Backlogs. Task assignment. Due dates. Priorities. Labels. Subtasks. Milestone planning. Tracking bugs, features, art, audio, and release work.

    Service Information

    Setting Value Service name Vikunja Private IP address 192.168.2.121 Backend port TCP 3456 Public hostname projects.bytek.ca Deployment directory /opt/vikunja Application container vikunja Database container vikunja-db Database PostgreSQL Reverse proxy Traefik Authentication Authentik OIDC Container user UID 1000 and GID 1000 Backup coverage Proxmox scheduled backup Proxmox VM ID Confirm current VM ID

    Application:

    Open Vikunja

    Components

    The deployment contains two main containers:

    Container Purpose vikunja Application API and web interface vikunja-db PostgreSQL database

    The application and database communicate through a private Docker network.

    PostgreSQL is not exposed publicly.

    Persistent Data

    Path Purpose /opt/vikunja/files Uploaded task attachments /opt/vikunja/postgres PostgreSQL data /opt/vikunja/config.yml Vikunja configuration /opt/vikunja/.env Database password and service secrets /opt/vikunja/compose.yml Docker Compose configuration

    The .env and config.yml files contain sensitive values and must not be copied into BookStack.

    Request Flow

    Internal Access

      The client resolves projects.bytek.ca through Pi-hole. Pi-hole returns Traefik at 192.168.2.182. Traefik receives the HTTPS request. Traefik forwards the request to 192.168.2.121:3456. Vikunja responds.

      External Access

        WHC DNS resolves projects.bytek.ca to 38.29.213.101. The VPS receives the HTTPS request. Traffic travels through WireGuard. The WireGuard gateway forwards the request to Traefik. Traefik forwards the request to 192.168.2.121:3456.

        Traefik Configuration

        Setting Value Hostname rule projects.bytek.ca Entry point websecure Certificate resolver letsencrypt Backend http://192.168.2.121:3456 Host-header forwarding Enabled Authentik ForwardAuth Disabled

        Vikunja uses native OIDC. Do not attach Authentik ForwardAuth to the Traefik router.

        DNS

        Public DNS

        WHC resolves:

          projects.bytek.ca to 38.29.213.101

          Internal DNS

          Pi-hole resolves:

            projects.bytek.ca to 192.168.2.182

            The Vikunja backend IP is not published in DNS.

            Authentication

            Vikunja uses native Authentik OpenID Connect.

            Setting Value Authentik application Vikunja Application slug vikunja Provider type OAuth2/OpenID Connect Client type Confidential Subject mode User UUID Callback https://projects.bytek.ca/auth/openid/authentik Scopes openid profile email Required group bytek-users Required policy Allow bytek.ca users Policy engine ALL

            A user must:

              Belong to bytek-users. Pass the Allow bytek.ca users policy.

              Local Authentication

              Local authentication remains available as a recovery method.

              Local authentication should not be disabled until:

                Authentik login works for both project members. OIDC account provisioning has been tested. Proxmox backups have succeeded. A restore has been tested. Local recovery credentials are stored securely.

                Container Runtime Identity

                The Vikunja container runs as:

                  UID: 1000 GID: 1000

                  The attachment directory should have:

                    Owner: 1000:1000 Mode: 0755 Writable: Yes

                    The container is explicitly configured to run as user 1000:1000.

                    Permission Validation

                    Run the Vikunja diagnostic command:

                    sudo docker exec vikunja /app/vikunja/vikunja doctor

                    The file-storage section should report:

                      Directory exists. Directory owner is 1000:1000. Ownership matches. Directory is writable. Disk space is available.

                      Check the container identity using:

                      sudo docker exec vikunja id

                      Expected identity:

                        UID 1000. GID 1000.

                        Docker Management

                        Move to the deployment directory:

                        cd /opt/vikunja

                        Validate Compose:

                        sudo docker compose config --quiet

                        Check container state:

                        sudo docker compose ps

                        View recent logs:

                        sudo docker compose logs --tail 100 vikunja db

                        Apply normal configuration changes:

                        sudo docker compose up -d

                        Recreate only the application container:

                        sudo docker compose up -d --force-recreate vikunja

                        Pull updated images and apply them:

                        sudo docker compose pull && sudo docker compose up -d

                        Do not use docker compose down -v.

                        The -v option can remove Docker-managed volumes.

                        Health Endpoint

                        Vikunja provides a health endpoint at:

                          /health

                          Direct health URL:

                          http://192.168.2.121:3456/health

                          Routed health URL:

                          Open Vikunja Health

                          Expected result:

                            HTTP 200.

                            Use the health endpoint rather than the interactive login page for monitoring.

                            Direct Validation

                            From the Vikunja VM:

                            curl -i http://127.0.0.1:3456/health

                            From the Traefik VM:

                            curl -i http://192.168.2.121:3456/health

                            From the Uptime Kuma VM:

                            curl -i http://192.168.2.121:3456/health

                            All three tests should return HTTP 200.

                            Firewall Requirements

                            The Vikunja VM should permit:

                            Source Port Purpose Home LAN or administrative workstation TCP 22 SSH administration 192.168.2.182 TCP 3456 Traefik backend access 192.168.2.115 TCP 3456 Uptime Kuma direct monitor 192.168.2.115 ICMP Optional ping monitor

                            TCP port 3456 must not be exposed publicly through the router or VPS.

                            Monitoring

                            Monitor Type Target Vikunja VM Ping 192.168.2.121 Vikunja Backend Direct HTTP http://192.168.2.121:3456/health Vikunja Through Traefik HTTPS https://projects.bytek.ca/health Vikunja Certificate Certificate projects.bytek.ca

                            Expected health status:

                              HTTP 200.

                              If the VM monitor fails but the HTTP monitors succeed, ICMP is probably blocked.

                              Database Backup

                              The PostgreSQL database can be exported using:

                              sudo docker compose exec -T db pg_dump -U vikunja vikunja > vikunja-backup.sql

                              Verify that the file was created:

                              ls -lh vikunja-backup.sql

                              Database dumps contain application data and must be protected.

                              Do not leave old unencrypted dumps accumulating on the VM.

                              Proxmox Backup

                              The Vikunja VM is included in the scheduled Proxmox backup job.

                              The backup protects:

                                Debian. Docker. PostgreSQL data. Attachments. Vikunja configuration. OIDC configuration. Compose file. Environment file.

                                A stopped baseline backup may be created after a known-good configuration.

                                Routine backups may use snapshot mode.

                                Project Structure

                                The current recommended structure is:

                                Main Project

                                  Game

                                  Subprojects

                                    Game Design Programming Art and Animation Audio Levels and Content QA and Bugs Release Marketing

                                    Workflow Columns

                                      Ideas Backlog Ready In Progress Review or Playtest Blocked Done

                                      Suggested Labels

                                        Feature Bug Design Code Art Audio Level Balancing Performance Playtest Release Blocker Nice to Have

                                        Common Failures

                                        Vikunja Is Reachable Directly but Not Through the Hostname

                                        Check:

                                          Pi-hole record. Traefik router. Traefik backend IP. Certificate. Proxmox firewall. Traefik logs.

                                          Health Endpoint Is Unreachable

                                          Check:

                                            Docker service. Vikunja container. PostgreSQL container. TCP port 3456. Guest firewall. Application logs.

                                            Authentik Login Does Not Appear

                                            Check:

                                              OIDC configuration in config.yml. Configuration-file mount. Client ID and secret. Authentik discovery URL. Callback URI. Vikunja logs. Container DNS.

                                              Authentik Returns Permission Denied

                                              Check:

                                                User membership in bytek-users. Allow bytek.ca users policy result. No unintended bytek-admin binding. Policy engine mode is ALL.

                                                Attachments Fail

                                                Check:

                                                  /opt/vikunja/files. Owner 1000:1000. Directory is writable. Container user is 1000:1000. Disk space. Vikunja doctor output.

                                                  Database Is Unavailable

                                                  Check:

                                                    vikunja-db container. PostgreSQL health check. Database credentials. Docker network. Free disk space. PostgreSQL logs.

                                                    Power-Failure Recovery

                                                      Confirm Proxmox is running. Confirm Pi-hole. Confirm Authentik. Confirm Traefik. Confirm the Vikunja VM owns 192.168.2.121. Confirm Docker is active. Confirm the PostgreSQL container. Confirm the Vikunja container. Test the direct health endpoint. Test the routed health endpoint. Test Authentik login. Test project and task access.

                                                      If OIDC fails after startup, verify DNS from the Vikunja VM before changing credentials.

                                                      Recovery Procedure

                                                      If Vikunja is unavailable:

                                                        Confirm the VM is running. Confirm the VM address. Confirm available disk space. Confirm Docker. Confirm PostgreSQL. Confirm the Vikunja container. Review logs. Test /health. Run Vikunja doctor. Test Traefik. Test Authentik only after application health is restored.

                                                        If the VM must be restored:

                                                          Restore the current backup under a temporary VM ID. Disconnect the restored VM network adapter. Confirm Docker. Confirm PostgreSQL. Confirm attachments. Confirm configuration files. Shut down the failed production VM. Assign the expected network identity. Start the restored VM. Confirm 192.168.2.121. Test direct health. Test routed health. Test OIDC.

                                                          Validation Checklist

                                                            Vikunja VM owns 192.168.2.121. Docker is active. PostgreSQL is healthy. Vikunja container is running. TCP port 3456 responds. /health returns HTTP 200. Attachment directory is writable. Container runs as 1000:1000. Traefik routes projects.bytek.ca. Certificate is valid. Authentik login works. Both project members can sign in. Task assignment works. Attachment upload and download work. Uptime Kuma monitors are healthy. Proxmox backup includes the VM. Database export has been tested. Offline restore has been tested.

                                                            Document Control

                                                              Owner: Bryan Gagne-Plante Private address: 192.168.2.121 Backend port: TCP 3456 Public hostname: projects.bytek.ca Deployment directory: /opt/vikunja Database: PostgreSQL Authentication: Authentik OIDC Required group: bytek-users Container identity: 1000:1000 Proxmox VM ID: Confirm current VM ID Last verified: YYYY-MM-DD Last OIDC test: YYYY-MM-DD Last attachment test: YYYY-MM-DD Last database-export test: YYYY-MM-DD Last restore test: YYYY-MM-DD Known limitation: Vikunja availability depends on one application VM and its local PostgreSQL container
                                                              Back to top