(Disclosure: AI helped me with this and I'm new to Traefik and this is a work in progress. Open to any suggestions.)
A highly secure reverse proxy architecture built with Traefik v3. Designed to securely expose internal homelab services (Plex, Jellyfin, Home Assistant) to the internet while maintaining strict access controls, automated SSL, and real-time threat protection.
- Traefik v3 (Native Install): High-performance routing using the robust File Provider architecture.
- Automated SSL (Dual Resolvers): Uses Let's Encrypt with Cloudflare DNS-01 for wildcard homelab certificates (
*.starklab.mkroshana.cominacme.json), plus a separate HTTP-01 resolver (letsencrypt-httpinacme-http.json) for external work domains outsidemkroshana.com(e.g.,n8n.jobpromax.it.com). - CrowdSec Integration: Built-in CrowdSec bouncer middleware to actively block malicious IPs and known threats in real-time.
- Defense-in-Depth Security:
- Strict security headers (HSTS, XSS protection, Frame Deny).
- Rate limiting on global routes and aggressive rate limiting on authentication endpoints.
- "Catch-All" router to drop unrecognized host requests.
- Internal dashboard access strictly protected by automated Basic Auth and LAN-only IP allowlisting.
- Modular & Scalable: Individual
.yamlconfiguration files for each service, allowing you to seamlessly plug in new applications without touching core routing logic. - Automated Deployment: A smart
deploy.shengine that natively handles password hashing, secure credential injection via.env, and configuration deployment.
stark-lab/
βββ traefik-setup/
β βββ .env.example # Template for required secrets
β βββ deploy.sh # Automated deployment and hashing script
β βββ traefik.yaml # Core static Traefik configuration
β βββ conf.d/ # Dynamic service routing configurations
β βββ _shared.yaml # Global middlewares (Crowdsec, Headers, Rate limits)
β βββ catch-all.yaml # Drops invalid traffic
β βββ dashboard.yaml # Secure Traefik dashboard
β βββ homeassistant.yaml# HA Routing
β βββ jellyfin.yaml # Jellyfin Routing
β βββ local-*.yaml # Local-only routing configurations (PVE, Unraid, etc.)
β βββ plex.yaml # Plex Routing
β βββ tls.yaml # Strict TLS/SNI enforcement
- A Linux server (e.g., Proxmox LXC running Ubuntu).
- Traefik v3 installed locally.
- A Cloudflare account managing your domain's DNS.
- CrowdSec installed with the Traefik Bouncer plugin.
-
Clone the repository:
git clone https://github.com/yourusername/stark-lab.git cd stark-lab/traefik-setup -
Configure your Environment: Copy the example environment file and fill in your secure credentials.
cp .env.example .env nano .env
β οΈ SECURITY WARNING: Never commit your.envfile to version control. It must remain in your.gitignore. -
Deploy: Run the deployment engine. The script will dynamically generate your Basic Auth hashes, securely inject your Cloudflare API tokens, and restart Traefik.
sudo chmod +x deploy.sh sudo ./deploy.sh
-
Verify: Navigate to the Traefik dashboard (e.g.,
https://traefik.local.yourdomain.com). Log in using theadminusername and the plain-text password you defined in your.envfile.
In addition to external access, this setup provides a secure local-only routing for specific subdomains using the *.local.yourdomain.com pattern. Services routed here use Traefik's block-external middleware, restricting access strictly to your home LAN.
Exposed Local Services:
- Traefik Dashboard (
https://traefik.local.yourdomain.comvia Basic Auth) - Jellyfin, Plex, Home Assistant, Seerr, Pterodactyl Panel (Reusing external backends)
- Duplicati (
https://10.x.x.x:8200) - Proxmox PVE1 (
https://10.x.x.x:8006viainsecure-transportSkipVerify) - Proxmox Backup Server PBS (
https://10.x.x.x:8007viainsecure-transportSkipVerify) - Unraid Tower (
https://10.x.x.xviainsecure-transportSkipVerify) - Pterodactyl Wings (
10.x.x.x:8080/:2022- Backend daemon/SFTP only)
For best performance and reliability, we employ both local DNS rewrites and a public DNS fallback:
- Local DNS (Pi-hole/AdGuard Router):
Add a wildcard DNS rewrite for
*.local.yourdomain.compointing to the Traefik LXC IP (10.x.x.x). This ensures instant connection without leaving your local network. - Cloudflare Fallback:
Create an A Record for
*.local.yourdomain.compointing to10.x.x.x(Proxy OFF / DNS-only). While returning a local/private IP via a public DNS resolver, it acts as a reliable fallback for devices without local DNS set up, and is safely protected against internet exploitation by theblock-externalrestriction rules.
To expose a new homelab service:
- Create a new file in
traefik-setup/conf.d/(e.g.,myservice.yaml). - Copy the structure from an existing file like
plex.yaml. - Update the
rulematching (e.g.,Host('myservice.yourdomain.com')) and point theloadBalancerto your internal IP and port. - Rely on Traefik's native rule-length sorting (avoid setting a hard
priorityunless strictly necessary) and attach the_shared.yamlmiddlewares to instantly secure the route. - CRITICAL STEP: Update
D:\Development\service_links.mdto track the new service's public/local URLs, VM ID, IP address, and port. - Re-run
sudo ./deploy.sh.
- Zero-Trust LAN: Even internal setups use strict routing. Services like the Traefik Dashboard and internal APIs use the
block-externalmiddleware to reject traffic originating outside the local subnets (10.x.x.x,192.168.x.x). - Hairpin NAT: Ensure your home router supports Hairpin NAT (NAT Loopback) so internal requests to your public domain dynamically loop back to Traefik.
- Port Forwarding: Forward Ports
80and443to your Traefik server (10.10.10.100). Port80handles HTTP β HTTPS redirects and Let's Encrypt HTTP-01 challenges for external work domains (letsencrypt-http).
All LXC containers on the Proxmox VE hypervisor (pve1 / 10.10.10.31) are provisioned via Proxmox VE Community Scripts and backed by ZFS storage (rpool). Updates across the estate follow a standardized, zero-downtime 5-step pipeline.
Each container and host update is executed sequentially (one guest at a time):
-
Pre-Update Audit Inspect active systemd services, current application versions, and pending APT upgrades before making changes:
ssh root@10.10.10.31 "pct exec <id> -- apt-get update && pct exec <id> -- apt list --upgradable" -
Direct ZFS Snapshot Take an atomic ZFS dataset snapshot on the Proxmox host before applying updates:
# Proxmox Host Root Pool ssh root@10.10.10.31 "zfs snapshot rpool/ROOT/pve-1@pre-pve-upgrade" # LXC Container Subvolume ssh root@10.10.10.31 "zfs snapshot rpool/data/subvol-<id>-disk-0@pre-<name>-update"
Why Direct ZFS Snapshots Instead of
pct snapshot: Proxmox'spct snapshotaborts withsnapshot feature is not availablewhenever an LXC container has host directory bind mounts attached (such as NFS media shares on111,115,117,118,120,121). Snapshottingrpool/data/subvol-<id>-disk-0directly at the ZFS layer is instantaneous and bypasses the bind-mount restriction. -
Community Script Application Update Run the Community Script entrypoint inside the container to upgrade the application binary, runtime dependencies (Node.js, Python
uv, PHP, Composer), and database migrations:ssh root@10.10.10.31 "pct exec <id> -- /bin/update"- Jellyfin (
CT 121) Note: Major Jellyfin upgrades (such as10.11.xto12.0+) perform irreversible SQLite schema migrations and alter the web client DOM, which can impactFile Transformation,Media Bar, and custom CSS themes. Verify plugin compatibility prior to major upgrades or pin the package version viaapt. - Home Assistant OS (
VM 150): Runs as a QEMU virtual machine appliance; updates are managed directly from the Home Assistant Web UI rather than host shell scripts.
- Jellyfin (
-
Base OS Package Upgrade & Cache Cleanup Upgrade underlying Debian/Ubuntu packages non-interactively so configuration file prompts never block execution, then purge APT caches:
ssh root@10.10.10.31 "pct exec <id> -- apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold dist-upgrade && pct exec <id> -- apt-get -y autoremove && pct exec <id> -- apt-get clean" -
Post-Update Health Verification Verify systemd daemon states, container runtimes (
docker ps/podman ps), and local HTTP response codes:ssh root@10.10.10.31 'pct exec <id> -- systemctl is-active <service> && pct exec <id> -- curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:<port>'For stopped/on-demand containers (
105,116,120,140,141,201), boot the container (pct start <id>), execute steps 1β5, verify service readiness, and power it back off (pct stop <id>).
| Target | Hostname | IP Address | Version Baseline | ZFS Rollback Snapshot |
|---|---|---|---|---|
| Host | pve1 |
10.10.10.31 |
Proxmox VE 8.3.4 (pve-manager 9.2.18, kernel 7.0.14-16) |
rpool/ROOT/pve-1@pre-pve-upgrade |
| CT ID | Hostname | OS | Application Version | Verification Port & Status | ZFS Rollback Snapshot |
|---|---|---|---|---|---|
| 100 | traefik |
Debian 12 | Traefik 3.7.13, CrowdSec 1.8.1 |
Ports 80/443, Bouncer :6060 (active) |
subvol-100-disk-0@pre-traefik-update |
| 101 | duplicati |
Debian 12 | Duplicati 2.4.0.0 |
Port 8200 (200 OK) |
subvol-101-disk-0@pre-duplicati-update |
| 102 | homelable |
Debian 12 | Homelable 3.4.2 |
Port 8000/docs (200 OK) |
β |
| 103 | tailscale |
Debian 12 | Tailscale 1.102.4 |
tailscaled (active) |
subvol-103-disk-0@pre-tailscale-update |
| 111 | qbittorrent |
Debian 12 | qBittorrent 5.2.3 (libtorrent 2.0.14) |
Port 8090 (200 OK) |
subvol-111-disk-0@pre-qbit-update |
| 113 | flaresolverr |
Debian 12 | FlareSolverr 3.5.0 (Docker) |
Port 8191 (200 OK) |
subvol-113-disk-0@pre-flaresolverr-update |
| 114 | prowlarr |
Debian 12 | Prowlarr 2.5.2.5491 |
Port 9696 (200 OK) |
subvol-114-disk-0@pre-prowlarr-update |
| 115 | bazarr |
Debian 12 | Bazarr 1.6.0 |
Port 6767 (200 OK) |
subvol-115-disk-0@pre-bazarr-update |
| 117 | radarr |
Debian 12 | Radarr 6.3.0.10514 |
Port 7878 (200 OK) |
subvol-117-disk-0@pre-radarr-update |
| 118 | sonarr |
Debian 12 | Sonarr 4.0.19.2979 |
Port 8989 (200 OK) |
subvol-118-disk-0@pre-sonarr-update |
| 119 | seerr |
Debian 12 | Seerr 3.4.1 (Node 22, pnpm 10) |
Port 5055 (307 Redirect) |
subvol-119-disk-0@pre-seerr-update |
| 121 | jellyfin |
Ubuntu 24.04 | Jellyfin 12.0.0 |
Port 8096 (200 OK) |
subvol-121-disk-0@pre-jellyfin-12 |
Non-personal work workloads migrated to pve1. Numbering convention: 210+ (10.10.10.21x on vmbr0) for self-managed work services.
| CT ID | Hostname | OS | Application / Role | Verification / Access | ZFS Rollback Snapshot |
|---|---|---|---|---|---|
| 210 | jpm-n8n |
Debian 13 | JobProMax n8n 2.45.7 (Node 24, migrated from Azure VM; n8n.jobpromax.it.com) |
Port 5678/healthz (200 OK), Traefik letsencrypt-http |
subvol-210-disk-0@pre-jpm-n8n-migrate |
| 211 | jpm-mail |
Debian 13 | ArcReach (Next.js 15.5.26, Node 22.23.5, PG 16.16; migrated from Azure; arcreach.thejobshelpers.com, mail.jobpromax.com) |
Port 3000/login (200 OK), Traefik letsencrypt-http, nightly pg_dump to Unraid |
subvol-211-disk-0@pre-arcreach-migrate |
| 212 | job-extractor |
Ubuntu 24.04 | Job Extractor (Python 3.12.3, spacy 3.7.2; migrated from Azure VM; outbound cron 0 2 * * * UTC) |
cron active, CI deploy webhook :9000 (/_hooks/job-extractor-deploy) |
subvol-212-disk-0@pre-job-extractor-migrate |
| CT ID | Hostname | OS | Application Version | Verification Port & Status | ZFS Rollback Snapshot |
|---|---|---|---|---|---|
| 105 | unifi-os-server |
Debian 13 | UniFi OS Server (Podman uosserver) |
Port 11443 (healthy, powered off) |
subvol-105-disk-0@pre-unifi-os-server-update |
| 116 | dispatcharr |
Debian 13 | Dispatcharr 0.30.0 (PG 16.15, Comskip V0.83) |
Port 9191 (200 OK, powered off) |
subvol-116-disk-0@pre-dispatcharr-update |
| 120 | plex |
Ubuntu 24.04 | Plex Media Server 1.42.2.10156 |
Port 32400/identity (200 OK, powered off) |
subvol-120-disk-0@pre-plex-update |
| 140 | pterodactyl-panel |
Debian 13 | Pterodactyl Panel 1.15.1 (PHP 8.4, MariaDB 11.8) |
Port 80 (200 OK, powered off) |
subvol-140-disk-0@pre-pterodactyl-panel-update |
| 141 | pterodactyl-wings |
Debian 13 | Pterodactyl Wings 1.13.3 (Docker CE 29.8.0) |
wings version (v1.13.3, powered off) |
subvol-141-disk-0@pre-pterodactyl-wings-update |
| 201 | n8n |
Debian 13 | n8n 2.38.7 (Node 24, npm 12) |
Port 5678/healthz (200 OK, powered off) |
subvol-201-disk-0@pre-n8n-update |
| VM ID | Name | Type | Update Mechanism | Status |
|---|---|---|---|---|
| 150 | haos |
QEMU VM (2048 MB RAM, 32 GB Disk) |
Home Assistant Supervisor Web UI | Running |