thoreau Maintenance

Common operational commands for thoreau. Most docker commands must run from /srv/docker (where compose.yml lives).

See also:

• thoreau architecture
• thoreau Backup and Restore

Services (Docker Compose)

All from /srv/docker:

Action	Command
Status	docker compose ps
Start all	docker compose up -d
Stop all	docker compose down
Restart one	docker compose restart <service>
Logs (follow)	docker compose logs -f <service>
Pull + recreate	docker compose pull && docker compose up -d

Service names: postgres redis vaultwarden paperless forgejo forgejo-runner

The stack is normally managed by systemd, not by hand:

Action	Command
Start/stop the whole stack	sudo systemctl start|stop selfhosted.service
Check stack unit	systemctl status selfhosted.service
Enable on boot	sudo systemctl enable selfhosted.service

Prefer docker compose for per-service work; use the systemd unit for full-stack start/stop so ordering (WireGuard → docker → stack) is respected.

WireGuard & tunnel

Action	Command
Tunnel status / handshake	sudo wg show
Bring tunnel up / down	sudo systemctl start|stop wg-quick@wg0
Forgejo SSH tunnel status	systemctl status forgejo-tunnel.service
Restart Forgejo SSH tunnel	sudo systemctl restart forgejo-tunnel.service

A healthy wg show shows a recent handshake with peer 10.100.0.1 and nonzero transfer. If git-over-SSH fails but web services work, suspect forgejo-tunnel.service.

Storage

Action	Command
Pool overview	sudo btrfs filesystem show
Usage / profile (per mount)	sudo btrfs filesystem usage /store/data
List subvolumes	sudo btrfs subvolume list /store/data
Quota usage	sudo btrfs qgroup show -reF /store/data
Scrub (integrity check)	sudo btrfs scrub start /store/data
Scrub status	sudo btrfs scrub status /store/data

Always query a mounted subvolume path (e.g. /store/data), not the bare /store directory — the latter reports the wrong filesystem.

Confirm raid1 on the HDD pool: sudo btrfs filesystem df /store/data should show Data, RAID1 and Metadata, RAID1.

Adding HDDs to the pool

sudo btrfs device add /dev/sdX /dev/sdY /store/data
sudo btrfs balance start -dconvert=raid1 -mconvert=raid1 /store/data

raid1 keeps two copies regardless of device count; mixed drive sizes are fine. Balance runs live but is slow on a full pool.

Health checks

External (from anywhere — proves the whole VPS→tunnel→thoreau path):

curl -sS https://code.bonhamlab.bio/api/v1/version
curl -sS -o /dev/null -w "%{http_code}\n" https://documents.bonhamlab.bio
curl -sS https://pw.bonhamlab.bio/alive

Local DB liveness:

docker exec selfhosted-postgres-1 psql -U postgres -c '\l'

Updates

System (Tumbleweed rolling — the one risky action):

sudo zypper dup

If an upgrade breaks the system, reboot and pick the pre-upgrade snapshot from the GRUB menu (snapper rollback). This is the safety net that makes rolling updates acceptable on a server.

Container images:

cd /srv/docker && docker compose pull && docker compose up -d

Runners

Runner admin (rename, remove, status) is in Forgejo’s web UI under Site Administration → Actions → Runners — not the user or repo scope, which only shows runners without full controls. Don’t edit the runner in the database.

Backups

Backup operations and restores are documented separately in thoreau Backup and Restore.