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

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

External Access

  1. WHC DNS resolves projects.bytek.ca to 38.29.213.101.
  2. The VPS receives the HTTPS request.
  3. Traffic travels through WireGuard.
  4. The WireGuard gateway forwards the request to Traefik.
  5. 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

  1. Confirm Proxmox is running.
  2. Confirm Pi-hole.
  3. Confirm Authentik.
  4. Confirm Traefik.
  5. Confirm the Vikunja VM owns 192.168.2.121.
  6. Confirm Docker is active.
  7. Confirm the PostgreSQL container.
  8. Confirm the Vikunja container.
  9. Test the direct health endpoint.
  10. Test the routed health endpoint.
  11. Test Authentik login.
  12. 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:

  1. Confirm the VM is running.
  2. Confirm the VM address.
  3. Confirm available disk space.
  4. Confirm Docker.
  5. Confirm PostgreSQL.
  6. Confirm the Vikunja container.
  7. Review logs.
  8. Test /health.
  9. Run Vikunja doctor.
  10. Test Traefik.
  11. Test Authentik only after application health is restored.

If the VM must be restored:

  1. Restore the current backup under a temporary VM ID.
  2. Disconnect the restored VM network adapter.
  3. Confirm Docker.
  4. Confirm PostgreSQL.
  5. Confirm attachments.
  6. Confirm configuration files.
  7. Shut down the failed production VM.
  8. Assign the expected network identity.
  9. Start the restored VM.
  10. Confirm 192.168.2.121.
  11. Test direct health.
  12. Test routed health.
  13. 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

No comments to display

Back to top