From c02c6307ce5ac718551007ca3982c1770f6109a3 Mon Sep 17 00:00:00 2001
From: Outis <outis1@duck.com>
Date: Mon, 1 Jun 2026 09:07:34 -0400
Subject: [PATCH] Revise README for Authelia integration and structure

Updated README.md to reflect new directory structure and added instructions for integrating Authelia with an existing Caddy setup.
---
 README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 90 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 5d7f42e..fc16d57 100644
--- a/README.md
+++ b/README.md
@@ -18,15 +18,17 @@ Single login covers all subdomains. Two-factor via TOTP app. Password reset via
 ## Directory structure
 
 ```
-~docker/
-├── caddy/
-│   └── Caddyfile          ← replace mydomain.com with real domain
+~/docker/
 ├── 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
+│   ├── .env
+│   ├── config/
+│   │   ├── configuration.yml
+│   │   ├── users.yml
+│   │   └── secrets/        ← never committed to git
+│   └── data/               ← never committed to git
+└── caddy/
+    └── Caddyfile
 ```
 
 ## First time setup
@@ -117,17 +119,94 @@ newservice.mydomain.com {
 }
 ```
 
+## Adding Authelia to an existing dockerized Caddy setup
+
+If you already have Caddy running with other services (e.g. via dothevo/selfhosted or similar),
+follow these steps to add Authelia without disturbing existing services.
+
+### 1. Find your existing Caddy Docker network
+```bash
+docker inspect caddy | grep -i network
+# or
+docker network ls
+```
+Note the network name — use it as `DOCKER_MY_NETWORK` in `authelia/.env`.
+
+### 2. Connect Authelia to that network
+In `authelia/docker-compose.yml` the network name must match your existing Caddy network.
+Authelia needs to be on the same network as Caddy to be reachable by container name.
+
+### 3. Add the authelia snippet to your existing Caddyfile
+Add at the top of your Caddyfile (before any site blocks):
+```caddyfile
+(authelia) {
+    forward_auth authelia:9091 {
+        uri /api/authz/forward-auth
+        copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
+    }
+}
+```
+
+Add the Authelia portal site block:
+```caddyfile
+auth.mydomain.com {
+    reverse_proxy authelia:9091
+}
+```
+
+### 4. Protect existing services
+For any existing service you want to protect, add `import authelia` to its site block:
+```caddyfile
+existingservice.mydomain.com {
+    import authelia          ← add this line
+    reverse_proxy container:port
+}
+```
+
+Services without `import authelia` are unaffected — they keep working exactly as before.
+
+### 5. Reload Caddy
+```bash
+docker exec -w /etc/caddy caddy caddy reload
+```
+
+### 6. Start Authelia
+```bash
+cd ~/docker/authelia && docker compose up -d
+```
+
+### Notes for existing setups
+- Authelia does NOT interfere with services that don't import the snippet
+- Services with their own login (Portainer, Nextcloud, etc.) should NOT use `import authelia`
+- If an existing service breaks after adding Authelia, remove `import authelia` from its block
+- The Authelia session cookie is scoped to your domain — it won't affect other domains you host
+
 ## 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)
+## Logging in
+
+**Username, not email.** Authelia's file backend uses the key name from `users.yml` as the login username, not the email address.
+
+Example — if `users.yml` has:
+```yaml
+users:
+  john:
+    email: john@example.com
+```
+Login with `john`, not `john@example.com`. The email is only used for TOTP registration and password reset emails.
 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
+2. Authelia emails a TOTP registration link — click it
+3. Authelia shows a QR code:
+   - **Password manager** (Bitwarden, 1Password) — may intercept and register automatically
+   - **Separate app** (Google Authenticator, Authy) — scan the QR code manually
+4. Enter the 6-digit code to confirm registration
+5. Every login after: username + password + 6-digit code
+
+Note: if using a password manager, it may complete TOTP setup without showing the QR code — this is normal and correct.
 
 ## Updating Authelia
 Only update when you have a specific reason (bug fix, security issue).