270 lines
7.1 KiB
Markdown
270 lines
7.1 KiB
Markdown
# 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/`
|
||
|