Home-Server Architecture

Technical documentation and operational standards for the home infrastructure powered by Docker, Traefik reverse proxy, and a secure mesh network.

Zero-Trust Mesh

Management plane isolation via WireGuard-encrypted overlay networking on Tailscale.

Edge Automation

Dynamic routing via Traefik with automated provisioning and renewal of Let's Encrypt TLS certificates.

Zero-Touch DNS

Scalable domain resolution powered by Cloudflare wildcards and automatic public IP synchronization.

1. Access & Security Guidelines

Administrative access enforces a minimal attack surface. Critical management services operate exclusively within the encrypted overlay mesh network.

Service / Interface	Environment	Port	Protocol / Auth
Shell Access (SSH)	Mesh VPN	`CustomPort`	Asymmetric Key Pairs (Password Auth Disabled)
Portainer Dashboard	Mesh VPN	`CustomPort`	HTTPS
Traefik Edge Routing	Public	`80` / `443`	HTTP (Redirect) / HTTPS (ACME TLS)

Perimeter Hardening: The host firewall (UFW) drops all incoming traffic not explicitly allowed, strictly exposing ports 80, 443, and the custom administrative SSH port, backed by Fail2Ban for proactive log analysis and dynamic IP banning.

2. Network Architecture & DNS Resolution

The diagram below illustrates the end-to-end traffic flow, physical boundary isolation, and the zero-trust administrative routing model:

Home-Server Detailed Network and Docker Architecture Diagram

Figure 1: Comprehensive Edge, Mesh, and Docker network topology.

To resolve previous ACME validation failures (such as SERVFAIL and CAA/AAAA query timeouts), authoritative DNS management is delegated to Cloudflare in passive mode (DNS Only).

Wildcard Record: Configured as *.domain.tld, routing any requested subdomain to the router's public IP without manual DNS record intervention.
DDNS Sync: A containerized worker queries and aligns the gateway's public IP address every 5 minutes.
Port Forwarding: The gateway forwards only incoming traffic on ports 80 and 443 to the server's local IP address.

3. Docker Infrastructure Management

All services operate inside isolated logical networks. The shared virtual bridge traefik-public serves as the single perimeter backbone for containers requiring public HTTPS routing.

# Provision the external bridge network for the reverse proxy
docker network create traefik-public

# Enforce strict file permissions for ACME cryptographic storage
chmod 600 acme.json

Databases and persistent backend storage services are never attached to traefik-public; they reside in isolated internal networks accessible only to their respective backend services.

4. Guidelines for New Services (Zero-Touch)

Deploying a new microservice requires no host port publishing (the direct use of host ports: bindings is prohibited). All routing rules are declared via Docker Labels.

services:
  app-backend:
    image: vendor/app:latest
    container_name: app-backend
    restart: unless-stopped
    networks:
      - traefik-public
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.app.rule=Host('app.domain.tld')"
      - "traefik.http.routers.app.entrypoints=websecure"
      - "traefik.http.routers.app.tls.certresolver=myresolver"

networks:
  traefik-public:
    external: true

5. Hardware Optimization (Headless Laptop)

When operating on laptop hardware, the host operating system must be tuned to inhibit ACPI sleep triggers and prevent lithium battery degradation.

Inhibit Sleep on Lid Close (systemd-logind)

Update /etc/systemd/logind.conf with the following directives:

HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore
HandleLidSwitchDocked=ignore

Battery Charge Threshold (80%)

# Enforce threshold via sysfs (applied on boot via cron)
echo 80 | sudo tee /sys/class/power_supply/BAT0/charge_control_end_threshold

# Or configure permanently via /etc/tlp.conf
START_CHARGE_THRESH_BAT0=75
STOP_CHARGE_THRESH_BAT0=80

6. Backup Strategy & Disaster Recovery

The backup pipeline leverages Rclone for automated, encrypted offsite synchronization to cloud storage.

Schedule: Daily automated run at 03:00 AM via cron.
Scope: Persistent database volumes, environment configurations (.env), certificate vaults (acme.json), and firewall state.
Retention Policy: Automatic purge of offsite archives older than 7 days.
Recovery: Interactive restoration workflow staged in an isolated, secure directory at /tmp/server_restore.

7. Telemetry & Hardware Metrics

A lightweight Python daemon polls core hardware metrics every minute and stores historical logs in structured CSV format (laptop_metrics.csv):

CPU utilization (%)
RAM allocation & capacity (%)
Motherboard thermal sensors (°C)