How to Deploy Authelia on a VPS

copysudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw status verbose

#Install Authelia

Create the project directory, with separate folders for configuration and secrets:

copymkdir -p ~/authelia/config ~/authelia/secrets && cd ~/authelia

#Secrets

Authelia needs three random secrets:

• the key that signs password-reset tokens;
• the session secret;
• the storage encryption key, which encrypts sensitive columns such as TOTP seeds in the database.

Authelia's documentation recommends loading them from files rather than putting them in the configuration. Generate each one once:

copyfor s in jwt session storage; do
  [ -f secrets/$s ] || openssl rand -hex 64 > secrets/$s
done
chmod 600 secrets/*
ls -l secrets

Back up secrets/storage with the database. Without it, the encrypted data in the database can't be read.

#The users database

With the file backend, users live in users_database.yml, and passwords are stored as Argon2 hashes. The Authelia image can create the hash. This block generates a random admin password, hashes it, writes the file, and prints the password once. It only runs if the file doesn't exist yet:

copyif [ ! -f config/users_database.yml ]; then
  ADMIN_PASS=$(openssl rand -base64 18)
  HASH=$(docker run --rm authelia/authelia:4.39 authelia crypto hash generate argon2 --password "$ADMIN_PASS" | sed -n 's/^Digest: //p')
  cat > config/users_database.yml <<EOF
users:
  admin:
    disabled: false
    displayname: 'Admin'
    password: '$HASH'
    email: 'admin@example.com'
    groups:
      - 'admins'
EOF
  echo "Authelia admin password (save it in your password manager now): $ADMIN_PASS"
fi
grep -c argon2id config/users_database.yml

To add users later, run docker run --rm authelia/authelia:4.39 authelia crypto hash generate argon2 interactively, add another entry under users:, and restart the container with docker compose restart authelia. Authelia doesn't pick up changes to the file on its own unless you set watch: true under authentication_backend.file.

#Configuration

Write the main configuration file. Replace example.com with your domain before going live:

copycat > config/configuration.yml <<'YAML'
server:
  address: 'tcp://:9091'

log:
  level: 'info'

totp:
  issuer: 'example.com'

authentication_backend:
  file:
    path: '/config/users_database.yml'

access_control:
  default_policy: 'deny'
  rules:
    - domain: '*.example.com'
      policy: 'two_factor'

session:
  cookies:
    - name: 'authelia_session'
      domain: 'example.com'
      authelia_url: 'https://auth.example.com'

storage:
  local:
    path: '/config/db.sqlite3'

notifier:
  filesystem:
    filename: '/config/notification.txt'
YAML

The sections that matter most:

• access_control starts from deny and then allows every subdomain with two_factor. Rules are checked in order, and the first match wins, so put specific rules, such as bypass for a public health endpoint or one_factor for a low-risk app, above the wildcard.
• session.cookies is where the domain requirement comes from. domain is the parent domain the cookie covers. authelia_url is where visitors without a session are sent.
• notifier: filesystem writes emails, such as two-factor registration links, to a file instead of sending them. That's fine for a single admin. For more users, replace it with an smtp block.

#Compose file

copycat > docker-compose.yml <<'YAML'
services:
  authelia:
    image: authelia/authelia:4.39
    container_name: authelia
    restart: unless-stopped
    volumes:
      - ./config:/config
      - ./secrets:/secrets:ro
    environment:
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: /secrets/jwt
      AUTHELIA_SESSION_SECRET_FILE: /secrets/session
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/storage
      TZ: UTC
    ports:
      # Loopback only: Caddy talks to Authelia, the internet doesn't.
      - "127.0.0.1:9091:9091"
YAML

Start it and wait for the health endpoint:

copydocker compose up -d
timeout 120 bash -c 'until curl -fsS http://127.0.0.1:9091/api/health; do sleep 3; done'; echo
docker compose logs --tail 20 authelia

{"status":"OK"} means the configuration loaded. Authelia checks its configuration at startup and refuses to start on errors, so if the health check never passes, the log says which key is wrong. A secret set both in a file and in configuration.yml also stops it from starting.

#HTTPS + domain via Caddy

Authelia doesn't serve TLS itself here. Caddy does, for the portal and for every protected app. Install Caddy as described in Automatic HTTPS with Caddy, then add one block for the portal and one per protected app:

auth.example.com {
    reverse_proxy 127.0.0.1:9091
}

app.example.com {
    forward_auth 127.0.0.1:9091 {
        uri /api/authz/forward-auth
        copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
    }
    reverse_proxy 127.0.0.1:8081
}

Every request to app.example.com now goes through Authelia first. Replace 127.0.0.1:8081 with wherever your app listens. copy_headers passes the signed-in user's name, groups and email on to the app. Apps that support trusted-header SSO can use those headers to log the user in automatically.

If Caddy runs as a container, use service names (authelia:9091) on a shared Docker network instead of 127.0.0.1.

#First login and two-factor setup

Open https://app.example.com. You should be redirected to https://auth.example.com. Sign in as admin with the password printed during install. Because the policy is two_factor, Authelia asks you to register a second factor. With the filesystem notifier, the one-time verification code is written to a file instead of an email:

copycat ~/authelia/config/notification.txt

Enter the code, then scan the TOTP QR code with an authenticator app or register a security key. After that you land on the protected app.

#Securing it

• Keep default_policy: deny. New subdomains stay closed until a rule allows them.
• Brute-force protection is on by default. The regulation section bans a user after repeated failed logins. The defaults are reasonable; tune max_retries, find_time and ban_time if you need to.
• Keep port 9091 on the loopback interface. The forward-auth endpoint trusts the X-Forwarded-* headers the proxy sends. If anyone else can reach Authelia directly, those headers can be forged.
• Use SMTP before you add other users, so password resets and two-factor registrations reach them.
• For more than a handful of users, move them from the YAML file to LLDAP or another LDAP directory. Authelia supports an ldap authentication backend.

#Backups

Three things together make a complete backup: the configuration (including users_database.yml), the SQLite database with registered devices and TOTP seeds, and the secrets, especially the storage encryption key. Stop the container for a consistent copy of the database. It restarts in seconds:

copycd ~/authelia
docker compose stop
tar czf authelia-backup-$(date +%F).tar.gz config secrets docker-compose.yml
docker compose start
ls -lh authelia-backup-*.tar.gz

The archive contains secrets and password hashes. Encrypt it (for example with gpg --symmetric) before you copy it off the server.

#Upgrades

The compose file pins the 4.39 release line, so pull picks up patch releases:

copycd ~/authelia
docker compose pull
docker compose up -d

To move to a new minor version, back up first, read that release's notes, then change the tag. Authelia sometimes renames or deprecates configuration keys between minor versions. It logs a warning for deprecated keys and still starts, so check docker compose logs authelia after every upgrade.

#Troubleshooting

Authelia exits right after starting. Read docker compose logs authelia. The configuration validator names the exact key. Common causes: a secret defined both in a file and in configuration.yml, a session.cookies.domain that doesn't contain the authelia_url host, or a secret file the container can't read.

Redirect loop between the app and the portal. The cookie domain doesn't cover both hosts, or the site is being reached over plain HTTP. The session cookie is secure-only, so everything must go through Caddy's HTTPS sites.

Every request gets "403 Forbidden" after login. No access_control rule matches that host, so default_policy: deny applies. Add a rule for the domain.

Login works, but the app doesn't know who you are. The app has to read the Remote-User header, and Caddy only passes it if it is listed in copy_headers. Many apps need a setting that enables trusted-header or proxy authentication.

#Verification + next steps

You're done when:

• https://auth.example.com loads with a valid certificate;
• visiting a protected app while signed out sends you to the portal;
• signing in requires your second factor;
• the backup archive, with secrets/storage inside it, is stored off the box.

From here, add a rule and a Caddy block for each app you want to protect. Use one_factor only where a password alone is acceptable. If you later need apps to sign in over OIDC rather than forward auth, Authelia also includes an OpenID Connect provider. For a passkey-only alternative, see Pocket ID, and for a heavier, all-in-one identity server see Keycloak.