Skip to content

🏠 Proxmox Home Server Documentation

Welcome to the official documentation for the 816931.xyz server infrastructure. This guide covers the hybrid cloud/home architecture, networking protocols, service maps, and maintenance procedures.

🏗️ System Architecture

Our infrastructure utilizes a Hybrid Gateway Model, leveraging a public Oracle VPS as a secure entry point to a local Proxmox Virtual Environment (PVE) at https://192.168.0.149:8006/.

1. The Gateway (Oracle VPS)

  • Public IP: 161.118.178.176
  • SSH User: ubuntu (Shortcut: ssh vps)
  • Role: Acts as a reverse proxy and secure entrypoint.
  • Mechanism: Caddy (Unified Infrastructure).
    • Local Services: status.816931.xyz and syncthing.816931.xyz are terminated locally with automatic HTTPS.
    • Home Services: All other *.816931.xyz traffic is reverse proxied to the home server (10.0.0.2:443) over WireGuard.
    • Stealth Services: Certain services like sta.816931.xyz are proxied to dedicated LXCs without being listed in public dashboards.
    • Automation: Configuration is automatically generated via Ansible (deploy_vps_caddy.yml).

2. The Internal Host (Proxmox)

  • Internal IP: 192.168.0.149
  • SSH User: root (Shortcut: ssh proxmox)
  • Web UI: https://192.168.0.149:8006/

3. The Bridge (WireGuard & SSH Tunnels)

  • Primary Tunnel (VPN): WireGuard connects VPS (10.0.0.1) to Home LXC 109 (10.0.0.2).
  • Monitoring Bridge (SSH): A persistent wud-tunnel.service on the Proxmox Host creates reverse SSH tunnels to the VPS.
    • Path: VPS 127.0.0.1:[2375-2376] -> Proxmox Host -> Internal LXC LAN IPs.

3. Home Traffic Controller (Caddy)

  • LXC ID: 106 (192.168.0.129)
  • Role: Handles SSL (Let's Encrypt DNS-01 via Cloudflare) and internal routing for all Proxmox services.
  • Automation: Configuration is automatically generated via Ansible.

4. Infrastructure Automation (Ansible)

  • LXC ID: 110 (Management node)
  • Tool: Ansible
  • Role: Orchestrates the configuration of Caddy (Home & VPS), Gatus, Homepage, and CoreDNS from a single source of truth.
  • Source of Truth: /root/homeserver/ansible/inventory/infrastructure_vars.yml
  • Primary Playbooks:
    • deploy_infra.yml: Deploys Home Caddy, Homepage, and CoreDNS.
    • deploy_vps_caddy.yml: Deploys VPS Caddy Gateway.
    • deploy_backups.yml: Manages Proxmox backup jobs.
  • Advanced Features: Supports Multi-Container Sidecars and Ansible Vault for encrypted secrets (secrets.yml).

5. Backup Engine (Syncthing)

  • Architecture: Uses a "3-Way Bridge" (iPad/PC ↔ VPS Relay ↔ Home HDD).
  • Relay (VPS): syncthing.816931.xyz (Port 8384).
  • Home Target: synchome.816931.xyz (LXC 108, Port 8086).
  • Storage: Files are synced to /mnt/external_drive on Proxmox.

🌐 Networking & DNS

Split DNS (CoreDNS)

  • LXC ID: 117 (192.168.0.14)
  • Role: Sole internal DNS authority (Technitium removed).
  • Function:
    • Internal: Resolves domain names to the local Caddy IP (192.168.0.129) for Gigabit speeds.
    • Automation: Zone file db.816931.xyz is automatically generated via Ansible based on the global infrastructure variables.
    • External: Cloudflare uses a Wildcard A Record (*) pointing all subdomains to the Oracle VPS public IP (161.118.178.176).
  • Cloudflare Credentials:
    • Zone ID: 4046ccfee8a888ec734fb698534aab88
    • API Token: <REDACTED_CLOUDFLARE_TOKEN> (DNS Edit permissions)

🚀 Service Inventory

Cloud Hosted (VPS)

Service URL Role
Gatus https://status.816931.xyz Monitoring as Code status page.
Syncthing Relay https://syncthing.816931.xyz 24/7 Always-on sync bridge.

Home Hosted (Proxmox)

Service Access Type LXC/VM ID
Jellyfin https://jellyfin.816931.xyz Media Server (Docker).
Stremio https://stremio.816931.xyz Media LXC (Docker).
Syncthing Home https://synchome.816931.xyz Backup Target (Docker 108).
JioTV Go https://jiotv.816931.xyz LXC 108 (Docker)
Dispatcharr https://dispatcharr.816931.xyz IPTV Manager (Docker).
Erugo https://share.816931.xyz File sharing (Docker 108).
Homepage https://homepage.816931.xyz Dashboard (Docker 108).
Stirling PDF https://stirlingpdf.816931.xyz PDF Tools (Docker 108).
Suwayomi https://suwayomi.816931.xyz Manga Server (Docker 108).
ConvertX https://convertx.816931.xyz Unit Converter (Docker 108).
BentoPDF https://bentopdf.816931.xyz PDF Tools (Docker 108).
Paperless-ngx https://paperless.816931.xyz Document Management (Docker 108).
Instagram Monitor https://sta.816931.xyz Stealth OSINT (LXC 119).
Home Assistant Internal IP:8123 Home Automation (VM 100).
Nextcloud Decommissioned Replaced by Syncthing.

🔄 Monitoring & Updates

We use Gatus for "Monitoring as Code" and Centralized Update Management via Ansible.

Gatus (Monitoring as Code)

Gatus replaces Uptime Kuma and AutoKuma. It uses a single YAML file to define all monitors. - Location: VPS (using network_mode: host). - Port: 8085 (proxied via VPS Caddy to 80/443). - Config Path: /home/ubuntu/gatus/config/config.yaml on the VPS. - Automation: Endpoints are automatically generated from the Ansible infrastructure_services list in infrastructure_vars.yml. - SSL Automation: The VPS Caddy handles SSL termination using Let's Encrypt for status.816931.xyz.

Homepage (Automation)

Homepage provides a centralized dashboard on LXC 108. - Automation: services.yaml is automatically generated via Ansible. - Clean State: Any service removed from infrastructure_vars.yml is automatically removed from the dashboard upon the next Ansible run, ensuring no residual entries. - Grouping: Services are automatically categorized into Core Services, Media, Tools, and Infrastructure based on the infrastructure_vars.yml configuration. - Duplicate Prevention: When using Ansible automation, Service Discovery should be disabled in settings.yaml to prevent Docker labels from creating redundant entries. - 🎨 Hybrid Icon Strategy: - The homepage_services.yaml.j2 template uses extension-based detection. - Local Icons: If the icon field ends in .png or .svg, it is served locally from /root/services/homepage/config/icons/ (mapped to /icons/filename.png). - Remote Slugs: If no extension is present, it defaults to the Homarr Dashboard Icons CDN. - Notable Local Icons: - jio.png (JioTV Go) - honey.png (Honey) - picoshare.png (Used for Erugo) - mkdocs.png (Documentation) - Slug Discovery: Search the Homarr metadata.json for slugs. Use curl -I to verify jsDelivr resolution before committing to a remote slug.

Container Organization

All containers on LXC 108 are organized into individual folders: * Path: /root/services/<service_name>/docker-compose.yml * Volumes: Persistent data is mapped to ./data/ relative to the compose file.

JioTV Go Auto-Update

Since JioTV Go is built from source, a custom update system is in place: * Update Script: /root/services/jiotv-go/update.sh * Schedule: Runs daily at 3:00 AM via crontab. * Mechanism: Pulls latest code from GitHub (develop branch) and triggers a docker compose up -d --build.

How to Update

Updates are automated via a systemd timer on the Management Node (LXC 110). - Manual Trigger: cd /root/homeserver/ansible && ansible-playbook -i inventory/hosts.ini playbooks/maintenance.yml --vault-password-file /root/homeserver/.vault_pass - Schedule: Daily at 03:00 AM. - Log Location: journalctl -u ansible-maintenance on LXC 110.

🛠️ Maintenance & Troubleshooting

Self-Healing Protocols

The system is configured to auto-recover from tunnel drops: * WireGuard Watchdog (LXC 109): A cron job (/usr/local/bin/wg-watchdog.sh) pings 10.0.0.1 every 2 minutes. If it fails, it restarts wg-quick@wg0. * Systemd Resiliency: Restart=always is enabled for critical services with a 10s delay.

Common Connectivity Fixes

  • Tunnel is down: Run systemctl restart wud-tunnel on the Proxmox Host.
  • SSH Public Key Denied: If the private key is encrypted with a passphrase, the CLI agent cannot connect non-interactively. Use ssh-add or remove the passphrase (ssh-keygen -p) to allow automation.
  • DNS Propagation Delays: When adding new subdomains, Uptime Kuma (on VPS) might show them as "Down" due to stale DNS. Use sudo resolvectl flush-caches on the VPS and restart the Uptime Kuma container. As a fallback, add the record to the VPS /etc/hosts.
  • Homepage "Host validation failed": Ensure the HOMEPAGE_ALLOWED_HOSTS environment variable is set to your dashboard domain (e.g., homepage.816931.xyz).
  • Homepage Missing Icons:
    1. Check the slug on dashboardicons.com.
    2. For custom icons, host them in /root/services/homepage/config/icons/ and map to /app/public/icons/.
    3. Use the label homepage.icon=/icons/filename.png (explicit path).
    4. Important: Homepage discovery automatically adds /icons/ if you only provide a filename. If you provide /icons/file.png, it becomes /icons/file.png internally. Avoid double slashes.
    5. Download Note: Always verify curled icons with the file command to ensure they aren't HTML error pages.
  • Homarr 500 Error: Ensure SECRET_ENCRYPTION_KEY is set in the environment.
  • LXC Docker not responding: Ensure the socat bridge is active inside the LXC: systemctl status docker-proxy.

CLI Rules (For AI & Admins)

  • Service Paths: Always operate within /root/services/<app>/ when editing compose files.
  • NEVER use the && operator in shell commands; execute them sequentially.
  • LXC IDs: Always verify actual IPs via pct list before configuring tunnels.
  • PROXMOX LXC COMMANDS: When executing commands inside an LXC from a remote SSH session, pct exec can misinterpret arguments. Use the -- separator to prevent this and wrap the command in bash -c.
    • Correct Example: ssh proxmox 'pct exec 108 -- bash -c "docker ps -a"'

Last Updated: February 20, 2026