BalserosWorld Homelab — Documentation

This repository is the single source of truth for the homelab. It replaces the previous monolithic README, kept as archivo/README_monolithic_2026-09-04.md for the record.

Last updated: 2026-09-07 · Language: English (the repo was translated from Spanish on 2026-09-04 so an agent reads it cheaply).

Pretty version: these same files, rendered — docs.balserosworld.net (Starlight, built and served by Cloudflare Pages so it stays up even when the homelab is down; see site/ and infra/networking.md § NET-15).

How this repo is maintained

Rule	Why
`state/` declares values, prose explains them	It is what makes the docs comparable against the real server
Each decision lives in its own file, not diluted in prose	A decision must be citable — `NET-05`, not “somewhere in §21”
Restore status is changed by a person, never by a process	It is a claim about a test someone ran, not an observable value
No secrets, in any file, ever	Tokens, TOTP, recovery keys, passphrases and webhooks live in Vaultwarden
If two files disagree, the most recent date wins	—

Map

Folder	What is in it
`infra/`	Proxmox, VM 100, VM 101, remote access, networking decisions
`services/`	Caddy, Nextcloud AIO, Jellyfin, monitoring (Loki/Prometheus/Grafana/Blackbox)
`concepts/`	DNS and routing, Docker networks, TLS, HTTP status codes, lessons
`backup/`	The two layers, R2, alerts, timers, incidents
`restore/`	The only thing that decides whether the homelab is protected
`runbooks/`	Repeatable procedures + the command cheatsheet
`archivo/`	History. Not edited.

Root files: architecture.md · operational-status.md · open-items.md · document-history.md

Where to start

"What state is the homelab in?"      →  this file, below
"What is still open?"                →  open-items.md
"How is it put together?"            →  architecture.md, infra/
"Why is traffic not arriving?"       →  concepts/http-status-codes.md
"How do I recover something?"        →  runbooks/recovery-model.md
"Why was it decided that way?"       →  infra/networking.md, backup/architecture.md
"What was that command again?"       →  runbooks/command-cheatsheet.md

Status at a glance — 2026-09-04

INFRASTRUCTURE
  Proxmox pve          192.168.2.200   OK   hardened, firewall active
  VM 100 docker-host   192.168.2.8     OK   Debian 13, Docker, all services
  VM 101 backup-mgr    192.168.2.10    OK   Borg repo + maintenance + R2 mirror
  VM 199 restore-test  (temporary)     !!   test passed — STILL TO BE DESTROYED

PUBLISHED SERVICES  (Caddy + DNS-01, *.balserosworld.net)
  vault.      Vaultwarden     OK       cloud.      Nextcloud AIO   OK
  portainer.  Portainer       OK       kuma.       Uptime Kuma     OK (substituted, pending decommission)
  test.       (lab)           commented out in the Caddyfile unless in use

  Jellyfin    deployed, details TO CONFIRM   → services/jellyfin.md
  Monitoring  Loki+Prometheus+Grafana+Blackbox deployed → services/monitoring.md

REMOTE ACCESS
  Tailscale            OK   subnet route 192.168.2.0/24 approved
  Cloudflare Tunnel    OK   created; off unless publishing something

BACKUP / DISASTER RECOVERY
  Layer 1  vzdump  → R2       OK     weekly, whole VM
  Layer 2  Borg    → VM101→R2 OK     daily 03:00, granular
  Nextcloud AIO native        OK     included as a Borg source
  Restore Vaultwarden         OK     VALIDATED END-TO-END (2026-09-01)
  Restore VM 100 from R2      OK     VALIDATED END-TO-END (2026-09-04)
  Restore Borg from R2        OK     valid by extension — see restore/r2-offsite.md
  Restore Nextcloud (full)    NO     NOT tested (deliberately deferred)

The four blockers that matter

#	Open item	Where
1	Destroy VM 199 — a clone carrying production’s IP, MAC and Tailscale identity	restore/vm100.md
2	Fill in the 13 `TO CONFIRM` gaps for Jellyfin and Netdata	services/
3	Pull one archive from `secure:borg-docker-host` and `borg list` it	restore/r2-offsite.md
4	A second independent physical medium — today Layer 1 and the Borg repo share one SSD	infra/vm101-backup-manager.md

Full list in open-items.md; component-by-component status in operational-status.md.

The BalserosWorld rule: a change important enough to break the homelab is important enough to document; a backup important enough to depend on is important enough to restore as a test.