Infrastructure Reference

Last updated: 2026-04-11 Database connections: See DATABASES.md DNS management: AdGuard Home at http://adguard.lan (#dns_rewrites) Credentials: ~/.credentials (per-host passwords), project-level in each repo's private/credentials

Network Overview

Two subnets on the domestic LAN, each served by a dedicated Proxmox host:

DNS for *.lan is managed by AdGuard Home on ca-server (192.168.1.97).

IP Allocation Scheme

192.168.2.0/24 (phoebe.lan)

192.168.1.0/24 (titan.lan)

Rule

Before assigning a new static IP, always:

1. Check this document
2. Check AdGuard rewrites: http://adguard.lan/#dns_rewrites
3. Scan the subnet: ip neigh show | grep "192.168.X\."

Physical Hosts

Proxmox Inventory: phoebe.lan

Virtual Machines

LXC Containers

Storage

Proxmox Inventory: titan.lan

Virtual Machines (active)

Virtual Machines (stopped -- templates, legacy, test)

LXC Containers

External Servers

SSH access: ssh jd@161.35.36.240, ssh jd@142.93.45.250

Key Services & Ports

On orcus.lan (192.168.2.32)

LLM Servers

Search & Torrents

DNS & Network

AdGuard Home: backing up DNS rewrites (runbook)

DNS rewrites and most other AdGuard Home settings live in the main configuration file AdGuardHome.yaml on the host that runs AdGuard (this network: ca-server / 192.168.1.97, UI at http://adguard.lan).

Why back up

• Rewrite lists are large and easy to lose if the CT/VM is rebuilt or the workdir is wiped.
• The YAML can also hold API credentials and upstream settings — treat backups as sensitive.

What to copy

• Primary: AdGuardHome.yaml from AdGuard’s working directory (typical locations: /opt/AdGuardHome/, or the path shown under Settings in the AdGuard UI). Confirm on the host with AdGuardHome --help / service unit / ps if unsure.
• Optional: the whole working directory if you also want filter lists and query logs policy; for DNS entries alone, the single YAML is usually enough.

Where to put backups (NAS)

• Store under the BACKUPS share on atrium: \\atrium\BACKUPS\adguard\ (create adguard once if missing). If BACKUPS is not mounted on the machine performing the copy, use another atrium backup path you already trust (see Storage (NAS Mounts on orcus.lan)).
• Use timestamped filenames, e.g. AdGuardHome-20260322T040001Z.yaml (UTC) or .yaml.gz when ADGUARD_BACKUP_GZIP=1 (see script below).
• Restrict permissions on the NAS folder (only admin accounts).

How (manual)

1. SSH to ca-server (or whichever host runs AdGuard Home).
2. Locate AdGuardHome.yaml (see above).
3. Copy to NAS with scp, rsync, or SMB mount; keep multiple generations (last 7 daily is a reasonable default).

Restore (outline)

1. Stop AdGuard Home (method depends on install: systemctl stop AdGuardHome or equivalent).
2. Replace AdGuardHome.yaml from a known-good backup (or merge carefully).
3. Start the service and verify rewrites in the UI (#dns_rewrites).

Tracked automation (weekly)

• Script (in git): scripts/backup-adguard-config.sh — copies AdGuardHome.yaml to BACKUPS\adguard with UTC timestamps, optional ADGUARD_BACKUP_GZIP=1, and count-based retention (default: keep newest 8 files).
• Runtime: ca-server (AdGuard host). Two modes:
  • CIFS mounted: set BACKUP_DEST_DIR to the adguard directory on a mounted //atrium.lan/BACKUPS (or //192.168.1.202/BACKUPS) tree. BACKUP_DEST_DIR is required in this mode.
  • smbclient mode (typical on LXC): kernel mount -t cifs may return “Operation not permitted” in unprivileged containers. Use ADGUARD_BACKUP_USE_SMBCLIENT=1 plus SMB_SERVER (often 192.168.1.202 — atrium.lan may not resolve inside the CT), SMB_SHARE=BACKUPS, SMB_SUBDIR=adguard, and SMB_CREDENTIALS_FILE pointing to a chmod 600 file with username= / password= lines. Run the script as root so it can read /opt/AdGuardHome/AdGuardHome.yaml (root-owned 0600).
• Deployed (ca-server, 2026-03): Script at /usr/local/sbin/backup-adguard-config.sh; SMB credentials at /home/jd/.smb-atrium-backups; root crontab weekly Sunday 04:00 with smbclient mode and SMB_SERVER=192.168.1.202. Log: /var/log/adguard-config-backup.log.
• Deploy / updates: Copy the script from the repo to /usr/local/sbin/, chmod 755.
• Cron: Example: 0 4 * * 0 (Sunday 04:00). Examples: infra/cron/ca-server-adguard-backup.cron.example (CIFS) and root crontab on ca-server (smbclient — see above).
• systemd timer: Alternative to cron — same script; one-shot timer weekly if you prefer.
• Security: Backup files can contain API credentials — do not commit them; restrict permissions on the NAS folder; keep SMB credential files chmod 600.
• Test backup (mandatory before cron): Run the script once manually with the same environment the cron job will use. Verify: exit code 0; a new AdGuardHome-*.yaml or .yaml.gz under \\atrium\BACKUPS\adguard\; non-zero size; plausible YAML (e.g. dns: / rewrite-related keys). Only then install the crontab line.
• Do not commit AdGuardHome.yaml or SMB passwords to git.

New Vhost and DNS Checklist

Use this checklist whenever adding a new hostname for a Zap app or any other local web service.

1. Choose the canonical hostname

• prefer short service-facing hostnames when that matches existing conventions
• keep the repo/app slug and the public hostname conceptually separate if that makes the URL cleaner
• decide whether the hostname is a local .lan host or a public domain/subdomain before making server changes

2. Add the web-server routing

• create or update the Apache vhost/reverse-proxy config under infra/apache/
• set the correct ServerName
• point DocumentRoot or proxy target at the real app entry point
• enable the site if needed and reload Apache
• verify Apache config validity before and after reload

3. Add the matching DNS entry

• before bulk edits: ensure AdGuard Home configuration backup is current (especially before adding many rewrites or rebuilding ca-server)
• for new .lan hostnames, add the DNS rewrite in AdGuard Home: http://adguard.lan/#dns_rewrites
• for new public domains or public subdomains, add DNS via Namecheap instead
• do not assume a vhost is reachable until DNS has been added as part of the same task

4. Verify reachability in the right order

• confirm hostname resolution first
• then verify the landing page
• then verify a health endpoint or equivalent low-cost endpoint
• only after routing and DNS both work should the hostname be treated as browser-testable

5. Update documentation

• update this file if the hostname becomes part of the continuing platform inventory
• add the hostname to the relevant app docs or README when useful
• update any project metadata that depends on the canonical URL

Notes

• .lan => AdGuard Home
• public domain/subdomain => Namecheap
• if DNS is not ready yet, a temporary path-based route on an already-working hostname can be useful for short-term testing, but it should not replace the canonical hostname

Local TLS and CA Reality

Current orcus TLS state

• orcus subdomains are currently being served by the local mkcert wildcard certificate, not by CA-server-issued per-host certificates.
• Verified active Apache cert paths on orcus include:
  • /var/www/zap/infra/ssl/orcus.lan+wildcard.pem
  • /var/www/zap/infra/ssl/orcus.lan+wildcard-key.pem
• Verified live TLS checks for extract.orcus.lan and polyglot.orcus.lan showed:
  • issuer: mkcert development CA
  • SAN includes DNS:*.orcus.lan
• Treat this as the current pragmatic working state, not as proof that the planned CA-server migration has already been completed.

What ca-server.lan is currently doing

• ca-server.lan (192.168.1.97) is currently a manual local CA workstation, not an automated issuing service such as step-ca.
• Verified CA material on ca-server.lan:
  • /home/jd/easy-rsa/pki/ca.crt
  • /home/jd/easy-rsa/pki/private/ca.key
• Verified CA workflow documentation on ca-server.lan:
  • /home/jd/cert-docs/README_atrium-lan_CA_DNS_CERTS.md
• The documented workflow is manual:
  • generate key + CSR
  • define SANs explicitly
  • sign with the Easy-RSA CA
  • copy/install the cert and key manually on the target host

Currently verified CA-managed names / artifacts

• atrium.lan
  • verified CA-issued cert on ca-server.lan
  • SAN includes DNS:atrium.lan and IP:192.168.1.202
• zap-msg.janus01.lan
  • verified CA-issued cert on ca-server.lan
  • SAN includes DNS:zap-msg.janus01.lan
• delphi.lan
  • cert, CSR, and key artifacts present on ca-server.lan
• backend.crt
  • older/internal CA-managed cert artifact present on ca-server.lan

Required future migration rule for orcus

• Do not assume Windsurf plans, chat summaries, or agent output mean CA migration has already happened.
• Before claiming a host uses the CA-server workflow, verify both:
  • the Apache SSLCertificateFile / SSLCertificateKeyFile paths
  • the live presented certificate via openssl s_client
• For each new orcus hostname, do one of the following explicitly:
  • document that it is temporarily using the current mkcert wildcard cert
  • or issue and install a dedicated CA-server certificate for that hostname
• Target end state for future cleanup:
  • generate dedicated key + CSR on ca-server.lan
  • include exact SANs for the hostname(s)
  • sign with the Easy-RSA CA
  • install on orcus with Apache-readable permissions
  • update the Apache vhost to use the CA-issued files
  • reload Apache and verify with openssl s_client

Storage (NAS Mounts on orcus.lan)

Content type paths on NAS:

VPN Configuration

vpn-fetch.lan (CT 300 on phoebe)

• OS: Alpine Linux
• VPN: PIA WireGuard (currently connected to PIA server; region varies)
• Purpose: Transmission torrent downloads routed through VPN
• PostUp route: ip route add 192.168.0.0/16 via 192.168.1.1 (LAN access preserved)

torrent-search.lan (CT 302 on phoebe)

• OS: Ubuntu 22.04
• VPN: PIA WireGuard (UK region preferred, auto-reconnect every 12h via cron)
• Purpose: Jackett + FlareSolverr Docker containers for 1337x torrent search
• PostUp route: ip route add 192.168.0.0/16 via 192.168.2.1 (LAN access preserved)
• Reconnect script: /usr/local/bin/pia-reconnect.sh
• Cron: 0 */12 * * * /usr/local/bin/pia-reconnect.sh >> /var/log/pia-reconnect.log 2>&1
• Docker: Jackett (port 9117) + FlareSolverr (port 8191), compose file at /opt/torrent-search/docker-compose.yml
• Jackett API key: stored in media-manager private/credentials

Web Apps on orcus.lan

All served via Apache with TLS. At present, the working local subdomains on orcus are still primarily using the local mkcert wildcard certificate for *.orcus.lan; they have not yet been fully migrated to CA-server-issued per-host certs. Each vhost maps a subdomain to a /var/www/<project>/ directory.

DNS Entries (AdGuard Rewrites)

Managed at http://adguard.lan/#dns_rewrites. Grouped by IP:

192.168.1.x

192.168.2.x