Skip to content

Vikunja Board Mirror Technical Specification

Overview & System Role

Vikunja operates as a single Docker container instance hosted on the greatroom PC (http://127.0.0.1:3456). It serves as the third leg of the fleet's board-redundancy architecture: 1. Jira: Primary source of truth. 2. BOARD.md: Canonical, git-replicated repository board. 3. Vikunja: Derived one-way read-only mirror.

This documentation addresses a visibility gap where fleet operators and automated readers were unaware of Vikunja's existence and operating parameters.

Data Flow & Sync Governance

Vikunja holds zero unique state. All task data is derived via one-way synchronization from Jira.

  • Sync Agent: FleetBoardSync scheduled task located at fleet-harness/ops/board-sync.
  • Single-Writer Constraint: FleetBoardSync MUST run exclusively on the greatroom PC. Never invoke sync tasks from secondary machines.
  • Immutability: Manual edits inside the Vikunja UI/API are strictly forbidden as they will be overwritten during sync cycles.

Authentication & Project Mapping

  • API Token Location: ~/.fleet-secrets/vikunja.json (Bearer token authentication).
  • Security Rule: Never log, print, or expose token values in CLI output or telemetry.
  • Project IDs:
  • 7 = FLT (Fleet Harness / Core infrastructure)
  • 8 = WING (WorkWingman)

Disaster Recovery & Operations (FLT-142)

Per the FLT-142 council decision (2026-07-19), hot High Availability (HA) was evaluated and rejected in favor of a lightweight disaster recovery model: - Nightly Backups: VikunjaNightlyBackup scheduled task outputs dumps to OneDrive. - Restore Verification: VikunjaRestoreVerify scheduled task routinely tests dump integrity. - Rebuild Strategy: Rebuild directly from Jira using: 

pwsh -File fleet-harness/ops/board-sync/Rehydrate-Vikunja.ps1 -FromJira
(Can be executed from any PC).

Critical Hazard: Database Restores

[!CAUTION] The -FromDump parameter in Rehydrate-Vikunja.ps1 drops and restores the database after validating the dump (size/header/version — validation added post-2026-07-29; an earlier version dropped before validating and once wiped the primary). It remains inherently destructive. Treat -FromDump as inherently destructive and strongly prefer -FromJira for all recovery operations.

Operational Verification

  • TODO(verify): Confirm exact cron/timer schedule intervals for FleetBoardSync, VikunjaNightlyBackup, and VikunjaRestoreVerify.