authelia-setup/README.md

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

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:

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

docker network create caddy_net

7. Start Authelia

cd ~/docker/authelia
mkdir -p data
sudo chown -R 1000:1000 config data
docker compose up -d
docker compose logs -f

8. Start Caddy

cd ~/docker/caddy
docker compose up -d

9. Generate Caddy basic auth hash (if using basic auth anywhere)

docker exec caddy caddy hash-password --plaintext 'yourpassword'

10. Reload Caddy after any Caddyfile changes

docker exec -w /etc/caddy caddy caddy reload

Adding a new protected service

In the Caddyfile add:

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)

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:

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