selfhosted2/23may2026-Q-server-prototype.md

Project "selfhosted2", 23may2026

Technical environment

Cross-development environment for prototyping a residential application server behind a VPS-style reverse proxy.

hector: The development machine. ASUS laptop running Linux Mint Mate. The machine on which this LLM session takes place (Session ID: ses_21ab382baffej8OpnTkrmaG5UA).

agge: Target machine acting as the 'Q Server'. Dell Optiplex mini PC running a headless Ubuntu Server. This is where the production apps reside. LAN IP 192.168.1.188, WireGuard IP 10.0.0.2.

raspen: Target machine acting as a VPS, with a reverse proxy routing all external traffic to applications on agge over an encrypted WireGuard tunnel. Raspberry Pi 5, running a headless Raspberry Pi OS Lite (64-bit). LAN IP 192.168.1.187, WireGuard IP 10.0.0.1.

The machines are connected through a dedicated local wifi hotspot, SSID NR-24. In the production deployment, raspen will be replaced by a cloud VPS with a public IP; the Docker compose and nginx configuration are designed to be portable as-is.

Architecture

hector
  │
  └──→ raspen.home (192.168.1.187) ← nginx reverse proxy (Docker)
          │                              wireguard sidecar (Docker)
          │                              wg0: 10.0.0.1/30
          │
          │  ──────────  WireGuard tunnel ──────────
          │
          │                              wg0: 10.0.0.2/30
          │                              Docker: Gitea, Nextcloud, PostgreSQL
          └──→ agge (192.168.1.188)

Raspen is the single entry point for all traffic. Nginx terminates SSL and proxies requests through the encrypted WireGuard tunnel to agge. No services are exposed on the plain LAN — Docker containers on agge bind exclusively to 10.0.0.2.

Network

Hosts file on hector (/etc/hosts):

192.168.1.187   raspen.home nc.home git.home pg.home
192.168.1.188   agge

Only raspen.home's IP is published to clients. agge has no direct domain mapping in the hosts file (it is addressed only by its WireGuard IP).

WireGuard VPN

Peer	Interface	IP	Port
raspen	wg0	10.0.0.1/30	ephemeral (outbound)
agge	wg0	10.0.0.2/30	51820/udp

Raspen runs WireGuard inside a Docker sidecar container (linuxserver/wireguard). Agge runs WireGuard as a native systemd service (wg-quick@wg0). UFW on agge allows UDP 51820 inbound.

Raspen's config (repo: vps/wireguard/wg_confs/wg0.conf):

• Connects to 192.168.1.188:51820
• Keepalive 25s
• Only routes 10.0.0.2/32 through the tunnel

Agge's config (/etc/wireguard/wg0.conf):

• Listens on port 51820
• Only accepts traffic from 10.0.0.1/32

Applications

VPS (raspen) — Docker stack

Location: vps/docker-compose.yml

Two containers sharing a network namespace:

• wireguard: Creates the VPN tunnel. Publishes ports 80, 443, 5432, 2222, and 51820/udp.
• nginx: Reverse proxy. Shares wireguard's network namespace (network_mode: "service:wireguard"). Proxies to agge via WireGuard IPs.

Nginx config (vps/nginx/conf.d/default.conf):

• nc.home:443 → 10.0.0.2:8080 (Nextcloud)
• git.home:443 → 10.0.0.2:3000 (Gitea)
• raspen.home:80/443 → static page
• HTTP redirects to HTTPS
• Self-signed SSL certs at vps/ssl/

TCP stream proxies (vps/nginx/stream.d/):

• pg.home:5432 → 10.0.0.2:5432 (PostgreSQL)
• git.home:2222 → 10.0.0.2:2222 (Gitea SSH)

Backend (agge) — Docker stack

Location: backend/docker-compose.yml

Four containers on an internal backend bridge network:

Container	Image	Ports (bound to 10.0.0.2)	Purpose
postgres	postgres:16-alpine	— (internal)	Database for Nextcloud
nextcloud	nextcloud:latest	8080:80	File sync & share
gitea	gitea/gitea:latest	3000:3000 (HTTP), 2222:22 (SSH)	Git hosting
postgres_remote	postgres:16-alpine	5432:5432	Remote-access DB

All published ports bind to 10.0.0.2 only, making them inaccessible over the plain LAN — traffic must arrive via the WireGuard tunnel.

Environment variables are loaded from .env (repo root).

Development

Working directory: /home/allan/Work/selfhosted2, a Git repo hosted on Gitea at agge. Two remote URLs are configured:

• https://git.home/scoot/selfhosted2.git (via raspen proxy — useful for read-only with self-signed cert)
• ssh://git@git.home:2222/scoot/selfhosted2.git (via raspen stream proxy — used for push)

Remote access:

• raspen: rasput@192.168.1.187
• agge: tebarbi@192.168.1.188

opencode configuration (opencode.json):

• Permission model asks before executing bash or accessing external directories.

Password management

Secrets are managed through a .env.example pattern:

• .env.example (tracked in git) — template with placeholder values documenting all required variables.
• .env (gitignored) — the actual secrets file on hector. A copy lives at ~/selfhosted2/.env on agge.
• Docker volumes — runtime copies of passwords baked into PostgreSQL and Nextcloud config on first deploy.

Password sources:

Variable	User	Where it's used	Where it's stored
POSTGRES_PASSWORD	nextcloud	Internal PostgreSQL (DB owner)	.env, Docker volume
—	oc_admin	Nextcloud app DB user	Nextcloud config.php
PG_PASSWORD	remoteuser	Remote PostgreSQL	.env, Docker volume
NEXTCLOUD_ADMIN_PASSWORD	admin	Nextcloud web login	.env, personal password manager

To rotate a password:

1. Generate: openssl rand -base64 18
2. Update .env and sync to agge
3. Run ALTER USER <user> WITH PASSWORD '<new>'; in the appropriate PostgreSQL container
4. If rotating the Nextcloud app user, also update config.php via sed
5. Restart the service if needed

Do not commit .env to git. The .env.example template is the only password-related file that belongs in the repo.

Deploy-time only

The .env file is read only during docker compose up (container create/recreate). At runtime, secrets live in Docker volumes and container env vars. Options for handling .env on the target machine:

Option	Security	Convenience
Keep with chmod 600 (current)	Root on agge can still read it — but root already owns the volumes	Compose works immediately
Remove after deploy	Minimal disk exposure	Must scp from hector before any docker compose down && up
Deploy script (deploy.sh)	.env lives only on hector, pushed transiently during deploy	Single command, cleanest for production

For the prototype, chmod 600 is fine. For a production VPS, a deploy script is better — the .env never sits on disk permanently.

Session history

Session ses_21ab382baffej8OpnTkrmaG5UA — initial prototype deployment: Docker files written, containers configured, applications deployed and verified.

Post-migration recovery (this session):

1. Hector was rebuilt from Omarchy Linux to Linux Mint Mate, losing the local work directory and self-signed certs.
2. The remote Gitea repo on agge was intact; the local repo was recovered via GIT_SSL_NO_VERIFY=1 git fetch over HTTPS (self-signed cert).
3. /etc/hosts was corrected — all domains now point to raspen (192.168.1.187) as the single entry point.
4. A WireGuard VPN was established between raspen (Docker sidecar) and agge (native systemd service).
5. Nginx upstream targets were changed from 192.168.1.188 to 10.0.0.2.
6. Docker port bindings on agge were restricted to 10.0.0.2 to enforce tunnel-only access.
7. UFW on agge was configured to allow WireGuard UDP 51820.
8. Gitea SSH port 2222 was added to nginx's TCP stream proxies on raspen, enabling git push over SSH through the VPN tunnel.
9. PostgreSQL passwords were rotated to strong values; .env replaced with .env.example pattern and gitignored; password management documented.

All services confirmed operational: Gitea (HTTP 200), Nextcloud (HTTP 302), PostgreSQL (port open), and static page (HTTP 200).