✨feature: Add gateway stack documentation
This commit is contained in:
Keith Solomon
309
content/gateway-stack.md
Normal file
309
content/gateway-stack.md
Normal file
@@ -0,0 +1,309 @@
|
|||||||
|
---
|
||||||
|
title: Gateway Documentation
|
||||||
|
section: docs
|
||||||
|
summary: Homelab Gateway — Traefik Reverse Proxy, Authelia SSO, LAN Routing, macvlan IP assignment, and Docker-managed services.
|
||||||
|
tags: [networking, traefik, authelia, infrastructure, docker, home-lab]
|
||||||
|
nav: 2
|
||||||
|
---
|
||||||
|
|
||||||
|
## Homelab Gateway Stack (Traefik + Authelia)
|
||||||
|
|
||||||
|
This document describes the architecture and configuration of the homelab gateway stack — the system responsible for HTTPS termination, reverse proxying, SSO-protected internal services, LAN-to-LAN routing, and stable external exposure.
|
||||||
|
|
||||||
|
This documentation intentionally mirrors the SoloForge Gitea documentation format for consistency across the infrastructure stack.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Overview
|
||||||
|
|
||||||
|
The Gateway Stack provides:
|
||||||
|
|
||||||
|
- **Reverse proxying via Traefik v3**
|
||||||
|
- **Authentication & SSO via Authelia v4**
|
||||||
|
- **Per-service routing with Docker labels or file-provider YAML**
|
||||||
|
- **macvlan-based static IP assignment (Traefik appears as its own LAN host)**
|
||||||
|
- **Secure exposure of internal services to the outside world**
|
||||||
|
- **ForwardAuth protection for otherwise unauthenticated apps**
|
||||||
|
- **Ability to proxy both Docker-based and remote LAN-based services**
|
||||||
|
|
||||||
|
This system replaces the previous Traefik + YAML editor stack and centralizes the “front door” of the homelab under a configuration that is fully self-documented, reproducible, and Git-tracked.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. System Layout
|
||||||
|
|
||||||
|
### 2.1 Host Machine
|
||||||
|
|
||||||
|
- Bare-metal machine (temporarily — will migrate back into Proxmox)
|
||||||
|
- Debian/Ubuntu-based environment
|
||||||
|
- Docker + Docker Compose v2+
|
||||||
|
- macvlan network configured so Traefik has a **dedicated LAN IP** (`192.168.2.253`)
|
||||||
|
|
||||||
|
### 2.2 Static Network Assignment (macvlan)
|
||||||
|
|
||||||
|
Traefik receives its own IP on the LAN:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker network create -d macvlan \
|
||||||
|
--subnet=192.168.2.0/24 \
|
||||||
|
--gateway=192.168.2.1 \
|
||||||
|
-o parent=eth0 \
|
||||||
|
traefik_macvlan
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rationale:**
|
||||||
|
|
||||||
|
- Makes Traefik behave like a true router on the network
|
||||||
|
- Allows the router to port-forward directly to Traefik instead of the host
|
||||||
|
- Eliminates host→Traefik conflicts
|
||||||
|
- Clean separation once this stack eventually lives in a VM or LXC again
|
||||||
|
|
||||||
|
### 2.3 Directory Structure
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/gateway/
|
||||||
|
├── traefik/
|
||||||
|
│ ├── traefik.yml # Static config
|
||||||
|
│ ├── config/ # File provider configs (GUI writes here)
|
||||||
|
│ ├── cert/ # ACME cert store
|
||||||
|
│ └── logs/ # Traefik logs
|
||||||
|
├── authelia/
|
||||||
|
│ ├── config/ # Authelia configuration.yml + users file
|
||||||
|
│ ├── secrets/ # Env-based secrets, if used
|
||||||
|
│ └── logs/ # Authelia logs
|
||||||
|
├── traefik-gui/
|
||||||
|
│ └── db/ # GUI internal sqlite db
|
||||||
|
└── traefik-stack.yml # Main stack
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Traefik Deployment
|
||||||
|
|
||||||
|
### 3.1 Traefik Service
|
||||||
|
|
||||||
|
Launched via Compose with two network attachments:
|
||||||
|
|
||||||
|
- `traefik_macvlan` → gives Traefik its LAN IP
|
||||||
|
- `proxy` → internal Docker network for app connectivity
|
||||||
|
|
||||||
|
Traefik is responsible for:
|
||||||
|
|
||||||
|
- HTTPS certificates via Let’s Encrypt (DNS-01 with Cloudflare)
|
||||||
|
- Routing per-service via hostnames
|
||||||
|
- Applying Authelia ForwardAuth checks
|
||||||
|
- Proxying internal Docker services and remote LAN machines
|
||||||
|
|
||||||
|
### 3.2 File Provider
|
||||||
|
|
||||||
|
The file provider watches:
|
||||||
|
|
||||||
|
`/traefik/config/`
|
||||||
|
|
||||||
|
Traefik GUI writes dynamic route definitions into this folder.
|
||||||
|
|
||||||
|
### 3.3 Docker Provider
|
||||||
|
|
||||||
|
Configured with:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
providers:
|
||||||
|
docker:
|
||||||
|
endpoint: "unix:///var/run/docker.sock"
|
||||||
|
exposedByDefault: false
|
||||||
|
network: proxy
|
||||||
|
```
|
||||||
|
|
||||||
|
Allows Traefik to auto-discover containers with labels on the `proxy` network.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Authelia (SSO / Authentication)
|
||||||
|
|
||||||
|
### 4.1 Purpose
|
||||||
|
|
||||||
|
Authelia handles:
|
||||||
|
|
||||||
|
- Single-sign-on for internal apps
|
||||||
|
- Multi-factor auth (optional)
|
||||||
|
- Protecting services with ForwardAuth (even those without native authentication)
|
||||||
|
- Login portal at `auth.keithsolomon.net`
|
||||||
|
|
||||||
|
### 4.2 Configuration Notes
|
||||||
|
|
||||||
|
- Config lives at `/authelia/config/configuration.yml`
|
||||||
|
- Secrets (session, storage encryption, reset-password JWT) supplied via environment variables
|
||||||
|
- SMTP notifier is required — missing credentials cause Authelia to crash-loop
|
||||||
|
- Logging set to stdout during debugging, file logging available once stable
|
||||||
|
|
||||||
|
### 4.3 ForwardAuth Middleware
|
||||||
|
|
||||||
|
Exposed to Traefik via labels:
|
||||||
|
|
||||||
|
`traefik.http.middlewares.authelia.forwardAuth.address=http://authelia:9091/api/authz/forward-auth`
|
||||||
|
|
||||||
|
Any protected service adds:
|
||||||
|
|
||||||
|
`traefik.http.routers.<service>.middlewares=authelia@docker`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. LAN Services & Routing
|
||||||
|
|
||||||
|
### 5.1 Dockerized Services (local to gateway)
|
||||||
|
|
||||||
|
Containers running on the same host as Traefik should:
|
||||||
|
|
||||||
|
1. Join the `proxy` network
|
||||||
|
2. Use Traefik Docker labels
|
||||||
|
3. NOT be accessed via the host IP (192.168.2.9) when Traefik is on macvlan
|
||||||
|
- macvlan cannot reliably reach the host’s bridge interfaces
|
||||||
|
|
||||||
|
Example (Sonarr):
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
labels:
|
||||||
|
- "traefik.enable=true"
|
||||||
|
- "traefik.docker.network=proxy"
|
||||||
|
- "traefik.http.routers.sonarr.rule=Host(`sonarr.keithsolomon.net`)"
|
||||||
|
- "traefik.http.services.sonarr.loadbalancer.server.port=8989"
|
||||||
|
```
|
||||||
|
|
||||||
|
Traefik will connect to `http://sonarr:8989` over the internal Docker network.
|
||||||
|
|
||||||
|
### 5.2 Remote LAN Services (other machines)
|
||||||
|
|
||||||
|
These should be added via the Traefik GUI (file provider), using the machine’s actual LAN IP:
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
docs:
|
||||||
|
loadBalancer:
|
||||||
|
servers:
|
||||||
|
- url: "http://192.168.2.51:8083"
|
||||||
|
```
|
||||||
|
|
||||||
|
These are not affected by the macvlan limitation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Gateway Compose Stack
|
||||||
|
|
||||||
|
**Services included:**
|
||||||
|
|
||||||
|
- traefik
|
||||||
|
- authelia
|
||||||
|
- traefik-gui
|
||||||
|
- eventually all internal homelab UIs
|
||||||
|
|
||||||
|
**Networks:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
networks:
|
||||||
|
traefik_macvlan:
|
||||||
|
external: true
|
||||||
|
proxy:
|
||||||
|
name: proxy
|
||||||
|
driver: bridge
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important: .env File**
|
||||||
|
|
||||||
|
Stores secrets such as Authelia session keys and SMTP passwords. Generate strong random hex values for the secrets using `openssl rand -hex 64`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
AUTHELIA_SESSION_SECRET=<hex>
|
||||||
|
AUTHELIA_STORAGE_ENCRYPTION_KEY=<hex>
|
||||||
|
AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET=<hex>
|
||||||
|
AUTHELIA_NOTIFIER_SMTP_PASSWORD=<app-password>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Operational Notes
|
||||||
|
|
||||||
|
### 7.1 Authelia Startup Failures
|
||||||
|
|
||||||
|
Authelia will crash-loop if:
|
||||||
|
|
||||||
|
- SMTP notifier missing password
|
||||||
|
- storage encryption key missing
|
||||||
|
- identity_validation.reset_password.jwt_secret missing
|
||||||
|
- configuration.yml malformed
|
||||||
|
|
||||||
|
Always check:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker logs Authelia
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7.2 macvlan Gotcha (Critical)
|
||||||
|
|
||||||
|
Traefik on macvlan **cannot reach the host’s own IP (192.168.2.9)**.
|
||||||
|
Use container names on the `proxy` network for same-host services.
|
||||||
|
|
||||||
|
### 7.3 Debugging Backend Connectivity
|
||||||
|
|
||||||
|
To simulate Traefik’s point of view:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run --rm -it --network=proxy alpine sh
|
||||||
|
apk add curl
|
||||||
|
curl -v http://sonarr:8989
|
||||||
|
curl -v http://192.168.2.51:8083
|
||||||
|
```
|
||||||
|
|
||||||
|
If container → hostIP fails, but container → container works, it’s macvlan isolation.
|
||||||
|
|
||||||
|
### 7.4 Traefik Dashboard
|
||||||
|
|
||||||
|
Available at `https://tfk.keithsolomon.net`
|
||||||
|
|
||||||
|
Protected by Authelia.
|
||||||
|
|
||||||
|
Check:
|
||||||
|
|
||||||
|
- Routers → status, errors, middlewares
|
||||||
|
- Services → backend URLs
|
||||||
|
- Middlewares → ensure authelia@docker exists
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Future Improvements
|
||||||
|
|
||||||
|
- Migrate gateway stack into Proxmox VM/LXC
|
||||||
|
- Replace Traefik-GUI with a cleaner UI (or maintain YAML by hand)
|
||||||
|
- Add Prometheus metrics for request/latency monitoring
|
||||||
|
- Add fail2ban or rate-limiting middleware
|
||||||
|
- Add OIDC provider configuration to Authelia for full single sign-on
|
||||||
|
- Automate propagation of routes from remote hosts (pull or push model)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TL;DR Cheat Sheet
|
||||||
|
|
||||||
|
**Traefik not routing?**
|
||||||
|
|
||||||
|
- → Check router → check service → check backend URL
|
||||||
|
- → If backend is on the same machine: use container name, not host IP
|
||||||
|
|
||||||
|
**Authelia crash-loop?**
|
||||||
|
|
||||||
|
- → Missing SMTP password
|
||||||
|
- → Missing storage/session/jwt secrets
|
||||||
|
- → Look inside /authelia/logs/authelia.log
|
||||||
|
|
||||||
|
**Adding a remote LAN service?**
|
||||||
|
|
||||||
|
- → Use Traefik GUI
|
||||||
|
- → Backend = `http://192.168.2.X:PORT`
|
||||||
|
- → Protect via Authelia middleware as needed
|
||||||
|
|
||||||
|
**Adding a local Docker service?**
|
||||||
|
|
||||||
|
- → Put it on the `proxy` network
|
||||||
|
- → Add Traefik labels
|
||||||
|
- → Use `loadbalancer.server.port`, not host IP
|
||||||
|
- → Do NOT use `192.168.2.9` when Traefik is on macvlan
|
||||||
Reference in New Issue
Block a user