# 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.

```bash
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:

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

Install Docker from Debian:

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

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

```bash
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:

```bash
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`

```yaml
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:

```bash
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:

```bash
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:

```text
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`:

```bash
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

```bash
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

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

Add:

```cron
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/`