homelab-notes/vikunja-lxc/vikunja-notes.md

Vikunja Self‑Hosted Setup (Debian LXC on Proxmox)

Overview

Self‑hosted Vikunja instance running in a Debian LXC on Proxmox, using Docker and Postgres 18 as the database.

Accessible at: http://<LXC-IP>:3456/ (example: http://10.0.10.159:3456/).

Proxmox / LXC

• Proxmox: LXC container, unprivileged, Debian 12 (bookworm)
• Network
  • Bridge: vmbr0
  • IPv4: DHCP (container gets 10.0.10.x from LAN)

DNS troubleshooting

Initial apt errors (“Temporary failure resolving deb.debian.org / security.debian.org”) were due to no route + bad DNS in the container.

Fixed by:

• Setting the container’s network device to bridge vmbr0 with IPv4 DHCP and restarting the LXC.
• Ensuring /etc/resolv.conf has working nameservers (router IP or 1.1.1.1, 8.8.8.8).

Backups

Use Proxmox container backups/snapshots on a schedule; this captures OS, Docker, DB, and Vikunja files.

Inside the LXC

System updates

Run periodically to keep Debian secure.

apt update
apt full-upgrade -y
reboot

Docker installation (from Debian repos)

Clean up any broken Docker repo (if present) to avoid NO_PUBKEY errors from an incomplete download.docker.com setup:

rm /etc/apt/sources.list.d/docker.list 2>/dev/null || true
apt update

Install Docker from Debian:

apt install -y docker.io
systemctl enable --now docker
docker --version

Install Docker Compose v2 plugin binary (official GitHub release):

mkdir -p /root/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/download/v2.29.2/docker-compose-linux-x86_64 \
  -o /root/.docker/cli-plugins/docker-compose
chmod +x /root/.docker/cli-plugins/docker-compose
docker compose version

Vikunja + Postgres layout

All Vikunja‑related files live under /opt/vikunja/:

• docker-compose.yml — main stack definition
• files/ — Vikunja attachments/uploads
• db/ — Postgres data directory (mounted to /var/lib/postgresql)

Create directories and set permissions:

mkdir -p /opt/vikunja/files
mkdir -p /opt/vikunja/db
chown -R 1000:1000 /opt/vikunja/files   # vikunja user in container
chown -R 999:999 /opt/vikunja/db        # postgres user in container

Docker Compose configuration

File: /opt/vikunja/docker-compose.yml

services:
  db:
    image: postgres:18
    container_name: vikunja-db
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: changeme # change to a strong password
      POSTGRES_DB: vikunja
    volumes:
      # Postgres 18+ expects a mount at /var/lib/postgresql,
      # not /var/lib/postgresql/data
      - /opt/vikunja/db:/var/lib/postgresql
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $${POSTGRES_USER}"]
      interval: 2s
      start_period: 30s

  vikunja:
    image: vikunja/vikunja
    container_name: vikunja
    depends_on:
      db:
        condition: service_healthy
    environment:
      VIKUNJA_SERVICE_PUBLICURL: http://10.0.10.159:3456/
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: changeme
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_SERVICE_JWTSECRET: <your-hex-secret>
    volumes:
      - /opt/vikunja/files:/app/vikunja/files
    ports:
      - "3456:3456"
    restart: unless-stopped

Replace:

• 10.0.10.159 with your LXC IP (or domain if you add a reverse proxy).
• <your-hex-secret> with a strong hex string:

openssl rand -hex 32

VIKUNJA_SERVICE_JWTSECRET signs login tokens; keep it stable across restarts.

Important notes / workarounds

Postgres 18+ mount change

Mounting /opt/vikunja/db to /var/lib/postgresql/data with Postgres 18 caused repeated errors about data in /var/lib/postgresql/data (unused mount/volume) and restarts.

For a fresh instance, fix with:

cd /opt/vikunja
docker compose down
rm -rf /opt/vikunja/db/*
chown -R 999:999 /opt/vikunja/db
# ensure compose mounts /opt/vikunja/db:/var/lib/postgresql
docker compose up -d

DB password mismatch

If docker logs vikunja shows:

pq: password authentication failed for user "vikunja"

Check that in docker-compose.yml:

• POSTGRES_USER == VIKUNJA_DATABASE_USER
• POSTGRES_PASSWORD == VIKUNJA_DATABASE_PASSWORD
• POSTGRES_DB == VIKUNJA_DATABASE_DATABASE

For a new setup, it may be simpler to wipe /opt/vikunja/db/* and restart with matching credentials.

Starting / stopping the stack

From /opt/vikunja:

cd /opt/vikunja
docker compose up -d     # start or update
docker compose down      # stop
docker ps                # status
docker logs vikunja      # app logs
docker logs vikunja-db   # DB logs

After up -d, go to http://<LXC-IP>:3456/ and create the first user; that account becomes the admin for its projects.

Quick troubleshooting checklist

No network / apt errors in LXC

ip a
ip route
ping -c 3 1.1.1.1
ping -c 3 deb.debian.org

• No IP / no default route → fix bridge/IPv4 config (vmbr0 + DHCP) in Proxmox and restart LXC.
• IP works but hostnames fail → fix DNS (/etc/resolv.conf, Proxmox DNS).

Postgres keeps restarting with mount error

• Confirm volume is /opt/vikunja/db:/var/lib/postgresql.
• For an empty instance, clear the directory and restart as above.

Vikunja keeps restarting

Check docker logs vikunja:

• DB auth error → fix credentials; reset DB if necessary.
• Other config errors → verify env vars (DB host/type, public URL, JWT secret).

Data and backups

Per Vikunja docs, back up:

• DB data: /opt/vikunja/db
• Files: /opt/vikunja/files

Proxmox backups

Schedule regular container backups so the whole LXC (OS + data) can be restored.

Optional DB dumps

mkdir -p /opt/vikunja/pg-dumps
crontab -e

Add:

0 3 * * * docker exec vikunja-db pg_dump -U vikunja vikunja > /opt/vikunja/pg-dumps/vikunja-$(date +\%F).sql

Ensure /opt/vikunja/pg-dumps is included in backups.

Usage notes / structure

Projects (namespaces)

Projects in the sidebar:

• Family
• Personal
• Properties
• Levkin (business)

Each project is its own list/board with multiple views (List, Gantt, Table, Kanban). Tasks are added via the “Add a task…” bar at the top of each project.

Labels

Current labels:

• Context: @home, @computer, @call, @errands
• Areas: Finance, Health, Legal, Maintenance, Deep
• People: Izik, Zane, Zoey
• Properties: #122, #153, #284, #45, #6, 5, 15

Suggestions:

• Normalize properties, e.g. P-122, P-153, etc.
• Add time/energy labels like 5min, 15min, “Low energy”, “High energy” for better filtering.

Use filters to combine labels (e.g. @computer + Deep, P-122 + Maintenance).

Useful links

• Docs: https://vikunja.io/docs/
• Config options: https://vikunja.io/docs/config-options/
• Docker walkthrough: https://vikunja.io/docs/docker-walkthrough/
• Full Docker example: https://vikunja.io/docs/full-docker-example/
• What to back up: https://vikunja.io/docs/what-to-backup/
• Community: https://community.vikunja.io/