From 3e6fa3a8f5c67e3e253246aeea24dd981ad8b68a Mon Sep 17 00:00:00 2001
From: Outis <outis1@duck.com>
Date: Mon, 1 Jun 2026 08:57:42 -0400
Subject: [PATCH] Update README with Authelia setup instructions

Added comprehensive setup instructions for Authelia and Caddy.
---
 README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)

diff --git a/README.md b/README.md
index 8b13789..b96bd13 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,144 @@
+# authelia-setup
 
+Reusable Authelia SSO + Caddy reverse proxy stack.
+Single login covers all subdomains. Two-factor via TOTP app. Password reset via SMTP.
+
+## What this does
+
+- **Caddy** — reverse proxy with automatic HTTPS via Let's Encrypt
+- **Authelia** — SSO portal at `auth.mydomain.com`, protects any subdomain with `import authelia` in the Caddyfile
+- **Brevo/Migadu SMTP** — sends TOTP registration and password reset emails
+
+## Machine requirements
+
+- Ubuntu 24.04 LTS
+- Docker: `curl -fsSL https://get.docker.com | sh && sudo usermod -aG docker $USER`
+- No GPU needed
+
+## Directory structure
+
+```
+homelab-auth/
+├── caddy/
+│   └── Caddyfile          ← replace mydomain.com with real domain
+├── authelia/
+│   ├── docker-compose.yml
+│   └── config/
+│       ├── configuration.yml  ← replace mydomain.com with real domain
+│       └── users.yml          ← replace mydomain.com, add real emails and hashes
+└── README.md
+```
+
+## First time setup
+
+### 1. DNS
+At your domain registrar add two records:
+```
+@   →  A      →  this machine's public IP
+*   →  CNAME  →  mydomain.com
+```
+
+### 2. Replace placeholders
+In every file replace `mydomain.com` with your real domain.
+In `users.yml` replace `REPLACE_WITH_HASH` with real password hashes (see below).
+
+### 3. Create secrets
+```bash
+mkdir -p ~/docker/authelia/config/secrets
+
+openssl rand -hex 32 > ~/docker/authelia/config/secrets/jwt_secret
+openssl rand -hex 32 > ~/docker/authelia/config/secrets/session_secret
+openssl rand -hex 32 > ~/docker/authelia/config/secrets/storage_secret
+echo "your-smtp-password" > ~/docker/authelia/config/secrets/smtp_password
+
+chmod 600 ~/docker/authelia/config/secrets/*
+```
+
+### 4. Create .env files
+`~/docker/authelia/.env`:
+```
+MY_DOMAIN=yourdomain.com
+SMTP_USER=authelia@yourdomain.com
+DOCKER_MY_NETWORK=caddy_net
+TZ=America/New_York
+```
+
+### 5. Generate password hashes
+Run once per unique password — all users can share one temporary password:
+```bash
+docker run --rm authelia/authelia:4.39.20 authelia crypto hash generate argon2 --password 'TempPass2026!'
+```
+Paste the output into `users.yml` for each user. Tell users to use "Forgot Password" on first login to set their own.
+
+### 6. Create Docker network
+```bash
+docker network create caddy_net
+```
+
+### 7. Start Authelia
+```bash
+cd ~/docker/authelia
+mkdir -p data
+sudo chown -R 1000:1000 config data
+docker compose up -d
+docker compose logs -f
+```
+
+### 8. Start Caddy
+```bash
+cd ~/docker/caddy
+docker compose up -d
+```
+
+### 9. Generate Caddy basic auth hash (if using basic auth anywhere)
+```bash
+docker exec caddy caddy hash-password --plaintext 'yourpassword'
+```
+
+### 10. Reload Caddy after any Caddyfile changes
+```bash
+docker exec -w /etc/caddy caddy caddy reload
+```
+
+## Adding a new protected service
+In the Caddyfile add:
+```caddyfile
+newservice.mydomain.com {
+    import authelia
+    reverse_proxy INTERNAL_IP:PORT
+}
+```
+Then reload Caddy. No Authelia changes needed.
+
+## Adding a service WITHOUT Authelia (has its own login)
+```caddyfile
+newservice.mydomain.com {
+    reverse_proxy INTERNAL_IP:PORT
+}
+```
+
+## Adding users
+1. Edit `~/docker/authelia/config/users.yml`
+2. Add user block with hash
+3. Restart Authelia: `docker compose restart authelia`
+4. Tell user to use "Forgot Password" to set their own password
+
+## TOTP setup (per user, first login)
+1. User logs in with username + temporary password
+2. Authelia emails a TOTP registration link
+3. User scans QR code with Google Authenticator, Authy, Bitwarden, or 1Password
+4. Every login after: username + password + 6-digit code
+
+## Updating Authelia
+Only update when you have a specific reason (bug fix, security issue).
+Change the version tag in `docker-compose.yml` then:
+```bash
+docker compose pull authelia
+docker compose up -d authelia
+```
+
+## Notes
+- Secrets never go in git — they live in `config/secrets/` which is gitignored
+- `.env` files never go in git
+- Session cookies are valid across all `*.mydomain.com` subdomains — one login covers everything
+- SQLite database lives in `~/docker/authelia/data/` — back this up to preserve user TOTP registrations