Caddy - Rad Web Hosting Blog

Learn How to Deploy Authelia On Debian VPS! This article provides a guide outlining how to deploy Authelia on Debian VPS. What is Authelia? Authelia is an open-source authentication and authorization server used to protect web applications with single sign-on, multi-factor authentication, and access-control policies. In practical terms, it sits in front of your apps and decides whether a visitor should be allowed in, challenged for login/MFA, or denied. Authelia describes itself as an IAM-style server and portal that provides MFA and SSO for applications through a web portal. It is commonly used with reverse proxies such as Nginx, Traefik, Caddy, and HAProxy. The reverse proxy receives the user’s request, asks Authelia whether the user is authorized, and then either forwards the request to the protected application or redirects the user to the Authelia login portal. A simple example: User visits app.example.com | v Nginx checks with Authelia | +--> Not logged in? Redirect to auth.example.com | +--> Logged in and allowed? Show the app | +--> Logged in but not allowed? Deny access Authelia is especially useful for self-hosted services that do not have strong built-in authentication. For example, you might put Authelia in front of: Portainer Grafana Prometheus phpMyAdmin BookStack Gitea Uptime Kuma internal admin panels private dashboards Key features include: Single sign-on across multiple apps Two-factor authentication TOTP support Security keys/passkeys Access control by domain, user, group, or network Reverse proxy integration OpenID Connect provider support File-based or LDAP-backed users SQLite, MySQL, or PostgreSQL storage In hosting terms, Authelia is like a security gatekeeper for web apps on your VPS. Instead of each application handling authentication separately, Authelia centralizes access control and lets you enforce stronger login requirements across multiple services. For example, without Authelia: app1.example.com has its own login app2.example.com has its own login app3.example.com has weak or no login With Authelia: auth.example.com handles authentication app1.example.com requires Authelia login app2.example.com requires Authelia login app3.example.com requires Authelia login + MFA It is a strong fit when you want to secure private web apps, admin panels, internal dashboards, or self-hosted tools behind a unified login system. Authelia is an open-source authentication and authorization gateway commonly used to add SSO, MFA, and access-control policies in front of self-hosted web applications. It is normally deployed behind a reverse proxy such as Nginx, Traefik, Caddy, or HAProxy. The Nginx integration uses the auth_request module to forward authorization checks to Authelia before proxying users to protected applications. This guide uses: Debian VPS Docker Compose Nginx reverse proxy Let’s Encrypt SSL via Certbot Authelia with file-based users SQLite storage for a small-to-medium deployment TOTP-based two-factor authentication Example protected app: app.example.com Authelia portal: auth.example.com Replace all example domains, usernames, emails, and passwords before using in production. Deployment Architecture The final layout will look like this: User Browser | | HTTPS v Nginx Reverse Proxy | | auth_request check v Authelia Container | | if authenticated v Protected Application Example hostnames: auth.example.com -> Authelia login portal app.example.com -> Protected backend application Authelia manages the login session cookie and determines whether a request should be allowed, denied, or redirected to the login portal. Its session configuration controls the cookie behavior and domains it can authorize. Prerequisites You need: Debian 12 or newer VPS Root or sudo user A domain name DNS access Ports 80 and 443 open At least 1 GB RAM, preferably 2 GB+ Create these DNS records before continuing: auth.example.com A YOUR_SERVER_IP app.example.com A YOUR_SERVER_IP For this guide, I will use: Main domain: example.com Authelia domain: auth.example.com Protected app: app.example.com Server public IP: 203.0.113.10 How to Deploy Authelia on Debian VPS To deploy Authelia on Debian VPS, follow the steps outlined below: Update Debian SSH into the VPS: ssh root@203.0.113.10 Update the system: apt update apt upgrade -y Install useful base packages: apt install -y ca-certificates curl gnupg lsb-release ufw nano openssl Set the system timezone if needed: timedatectl set-timezone America/Chicago Check: timedatectl Configure Basic Firewall Rules Allow SSH, HTTP, and HTTPS. ufw allow OpenSSH ufw allow 80/tcp ufw allow 443/tcp ufw enable Check status: ufw status verbose Expected: 22/tcp ALLOW 80/tcp ALLOW 443/tcp ALLOW Install Docker Engine Install Docker’s official repository key: install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/debian/gpg \ -o /etc/apt/keyrings/docker.asc chmod a+r /etc/apt/keyrings/docker.asc Add the Docker repository: echo \ "deb \ https://download.docker.com/linux/debian \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \ > /etc/apt/sources.list.d/docker.list Install Docker and Docker Compose plugin: apt update apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin Enable Docker: systemctl enable --now docker Verify: docker --version docker compose version Install Nginx and Certbot apt install -y nginx certbot python3-certbot-nginx Enable Nginx: systemctl enable --now nginx Check: systemctl status nginx --no-pager Create Authelia Directory Structure Create a dedicated directory: mkdir -p /opt/authelia/config mkdir -p /opt/authelia/data mkdir -p /opt/authelia/secrets cd /opt/authelia Lock down permissions: chmod 700 /opt/authelia/secrets Authelia’s documentation recommends treating values such as secrets, keys, passwords, and tokens as security-sensitive and avoiding accidental disclosure in shared configuration files. Generate Authelia Secrets Generate the JWT secret for reset-password identity validation: openssl rand -base64 48 > /opt/authelia/secrets/jwt_secret Generate the session secret: openssl rand -base64 48 > /opt/authelia/secrets/session_secret Generate the storage encryption key: openssl rand -base64 48 > /opt/authelia/secrets/storage_encryption_key Set permissions: chmod 600 /opt/authelia/secrets/* The storage encryption key is used to encrypt data in the database; Authelia recommends a random value of at least 64 characters, with a minimum length of 20 characters. Create Docker Compose File Create: nano /opt/authelia/docker-compose.yml Paste: services: authelia: image: authelia/authelia:latest container_name: authelia restart: unless-stopped volumes: - ./config:/config - ./data:/data - ./secrets:/secrets:ro environment: TZ: America/Chicago AUTHELIA_JWT_SECRET_FILE: /secrets/jwt_secret AUTHELIA_SESSION_SECRET_FILE: /secrets/session_secret AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/storage_encryption_key ports: - "127.0.0.1:9091:9091" This binds Authelia only to 127.0.0.1:9091, meaning it is reachable locally by Nginx but not exposed directly to the public internet. Authelia officially supports Docker deployment, and the Docker method is commonly recommended because the Authelia process does not need privileged host access when file permissions are configured correctly. Create the Main Authelia Configuration Create: nano /opt/authelia/config/configuration.yml Paste this starter configuration: theme: auto server: address: tcp://0.0.0.0:9091 log: level: info totp: issuer: example.com authentication_backend: password_reset: disable: false file: path: /config/users_database.yml identity_validation: reset_password: jwt_secret: '{{ secret "/secrets/jwt_secret" }}' access_control: default_policy: deny rules: - domain: auth.example.com policy: bypass - domain: app.example.com policy: two_factor subject: - group:admins session: cookies: - name: authelia_session domain: example.com authelia_url: https://auth.example.com default_redirection_url: https://app.example.com expiration: 1h inactivity: 5m remember_me: 1M regulation: max_retries: 5 find_time: 2m ban_time: 10m storage: encryption_key: '{{ secret "/secrets/storage_encryption_key" }}' local: path: /data/db.sqlite3 notifier: filesystem: filename: /data/notification.txt Important notes: default_policy: deny blocks anything not explicitly allowed. auth.example.com uses bypass so users can access the login portal. app.example.com requires two_factor. domain: example.com allows cookies to work across auth.example.com and app.example.com. The filesystem notifier is acceptable for testing, but SMTP is better for production. Authelia’s documentation specifically notes that file-based notifications are recommended only for testing, not production. For production, configure SMTP so users can receive password-reset and identity-validation messages by email. Generate an Authelia Password Hash Authelia stores hashed passwords in users_database.yml. Run this command and enter your desired password when prompted: docker run --rm -it authelia/authelia:latest \ authelia crypto hash generate argon2 Authelia’s current CLI supports Argon2 hash generation, with argon2id as the default variant. The output will look similar to: Digest: $argon2id$v19$m65536,t3,p4$... Copy the full hash beginning with: $argon2id$ Create the Users Database Create: nano /opt/authelia/config/users_database.yml Paste: users: admin: displayname: "Admin User" password: "$argon2id$v19$m65536,t3,p4$REPLACE_WITH_REAL_HASH" email: admin@example.com groups: - admins Replace: $argon2id$v19$m65536,t3,p4$REPLACE_WITH_REAL_HASH with the real hash generated in the previous step. Set permissions: chmod 600 /opt/authelia/config/users_database.yml Authelia supports file and LDAP authentication backends; this guide uses the file backend because it is simple and suitable for a first deployment or small environment. Validate the Authelia Configuration Authelia validates configuration at startup and can also validate it manually with the authelia config validate command. This checks for invalid keys, renamed keys, invalid values, and conflicting configuration options. Run: cd /opt/authelia docker run --rm \ -v /opt/authelia/config:/config \ -v /opt/authelia/data:/data \ -v /opt/authelia/secrets:/secrets:ro \ authelia/authelia:latest \ authelia config validate --config /config/configuration.yml If successful, continue. If you see errors, fix the reported configuration line before starting Authelia. Start Authelia cd /opt/authelia docker compose up -d Check status: docker ps View logs: docker logs authelia --tail100 You should see Authelia listening on port 9091. Test locally: curl -I http://127.0.0.1:9091 A response from Authelia confirms the container is reachable from the VPS. Create Nginx Site for Authelia Portal Create: nano /etc/nginx/sites-available/auth.example.com Paste: server { listen 80; server_name auth.example.com; location / { proxy_pass http://127.0.0.1:9091; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Original-URL $scheme://$http_host$request_uri; proxy_set_header X-Forwarded-Method $request_method; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Forwarded-Uri $request_uri; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; } } Enable it: ln -s /etc/nginx/sites-available/auth.example.com /etc/nginx/sites-enabled/ nginx -t systemctl reload nginx Issue SSL certificate: certbot --nginx -d auth.example.com Test: curl -I https://auth.example.com Visit: https://auth.example.com You should see the Authelia login portal. Create a Reusable Nginx Authelia Auth Snippet Create: nano /etc/nginx/snippets/authelia-authrequest.conf Paste: location /internal/authelia/authz { internal; proxy_pass http://127.0.0.1:9091/api/authz/auth-request; proxy_pass_request_body off; proxy_set_header Content-Length ""; proxy_set_header X-Original-Method $request_method; proxy_set_header X-Original-URL $scheme://$http_host$request_uri; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Forwarded-Uri $request_uri; proxy_set_header X-Real-IP $remote_addr; } auth_request /internal/authelia/authz; auth_request_set $redirection_url $upstream_http_location; error_page 401 302 $redirection_url; error_page 403 403 /authelia-forbidden; Create a simple forbidden response snippet: nano /etc/nginx/snippets/authelia-forbidden.conf Paste: location /authelia-forbidden { return 403 "Forbidden by Authelia access policy.\n"; } The Nginx auth_request flow requires Nginx to handle redirects because the authorization endpoint itself does not automatically redirect the browser; Authelia returns the redirect location for Nginx to use. Configure a Protected Application This example assumes your protected application listens locally on: 127.0.0.1:8080 Create: nano /etc/nginx/sites-available/app.example.com Paste: server { listen 80; server_name app.example.com; include /etc/nginx/snippets/authelia-authrequest.conf; include /etc/nginx/snippets/authelia-forbidden.conf; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Original-URL $scheme://$http_host$request_uri; proxy_set_header X-Forwarded-Method $request_method; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Forwarded-Uri $request_uri; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; proxy_set_header Remote-User $upstream_http_remote_user; proxy_set_header Remote-Groups $upstream_http_remote_groups; proxy_set_header Remote-Email $upstream_http_remote_email; proxy_set_header Remote-Name $upstream_http_remote_name; } } Enable: ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/ nginx -t systemctl reload nginx Issue SSL: certbot --nginx -d app.example.com Now visit: https://app.example.com Expected behavior: Nginx asks Authelia whether the request is authorized. If you are not logged in, you are redirected to https://auth.example.com. You log in. You enroll TOTP if needed. You are redirected back to https://app.example.com. Test with a Simple Temporary Backend If you do not already have an app running on 127.0.0.1:8080, you can start a temporary test server: docker run -d \ --name test-app \ --restart unless-stopped \ -p 127.0.0.1:8080:80 \ nginx:alpine Then visit: https://app.example.com You should be forced through Authelia before seeing the Nginx welcome page. Configure SMTP Notifications for Production Filesystem notifications write messages to a local text file and are useful for testing, but production deployments should use SMTP. Replace this section: notifier: filesystem: filename: /data/notification.txt With something like: notifier: smtp: address: submission://smtp.example.com:587 username: authelia@example.com password: "REPLACE_WITH_SMTP_PASSWORD" sender: "Authelia " A better production version is to store the SMTP password in /opt/authelia/secrets/smtp_password and reference it through an Authelia-supported secret method instead of hardcoding it in YAML. After changing the config: cd /opt/authelia docker compose restart authelia docker logs authelia --tail100 Add More Protected Domains For each new protected service, add a rule to configuration.yml. Example: access_control: default_policy: deny rules: - domain: auth.example.com policy: bypass - domain: app.example.com policy: two_factor subject: - group:admins - domain: dashboard.example.com policy: two_factor subject: - group:admins - domain: status.example.com policy: one_factor subject: - group:admins - group:users Then restart Authelia: cd /opt/authelia docker compose restart authelia Create an Nginx vhost for each app and include: include /etc/nginx/snippets/authelia-authrequest.conf; include /etc/nginx/snippets/authelia-forbidden.conf; Add Another User Generate a password hash: docker run --rm -it authelia/authelia:latest \ authelia crypto hash generate argon2 Edit users: nano /opt/authelia/config/users_database.yml Example: users: admin: displayname: "Admin User" password: "$argon2id$v19$m65536,t3,p4$ADMIN_HASH" email: admin@example.com groups: - admins john: displayname: "John Smith" password: "$argon2id$v19$m65536,t3,p4$JOHN_HASH" email: john@example.com groups: - users Restart: cd /opt/authelia docker compose restart authelia Enable Automatic SSL Renewal Certbot normally installs a systemd timer automatically. Check: systemctl list-timers | grep certbot Test renewal: certbot renew --dry-run If successful, Let’s Encrypt renewal is configured. Useful Management Commands Start Authelia: cd /opt/authelia docker compose up -d Stop Authelia: cd /opt/authelia docker compose down Restart Authelia: cd /opt/authelia docker compose restart authelia View logs: docker logs authelia --tail100 Follow logs live: docker logs -f authelia Validate configuration: docker run --rm \ -v /opt/authelia/config:/config \ -v /opt/authelia/data:/data \ -v /opt/authelia/secrets:/secrets:ro \ authelia/authelia:latest \ authelia config validate --config /config/configuration.yml Update Authelia: cd /opt/authelia docker compose pull docker compose up -d docker image prune -f Before updates, validate your configuration. Authelia’s documentation notes that configuration keys can change over time and that validation is useful before upgrades to avoid downtime. Backup Authelia Back up these directories: /opt/authelia/config /opt/authelia/data /opt/authelia/secrets Create a manual backup: mkdir -p /root/backups tar -czf /root/backups/authelia-$(date +%F).tar.gz \ /opt/authelia/config \ /opt/authelia/data \ /opt/authelia/secrets Protect the backup because it contains secrets: chmod 600 /root/backups/authelia-$(date +%F).tar.gz A complete restore requires: configuration.yml users_database.yml SQLite database JWT/session/storage secrets Do not lose the storage encryption key. If you lose it, encrypted Authelia storage data may become unusable. Hardening Recommendations Use these practices before placing important services behind Authelia: Use HTTPS only. Keep Authelia bound to 127.0.0.1, not public 0.0.0.0. Use two_factor for sensitive applications. Use SMTP instead of filesystem notifications. Use strong user passwords. Back up /opt/authelia/secrets securely. Keep Docker images updated. Validate configuration before upgrades. Use default_policy: deny. Create explicit allow rules per domain. Limit direct app access so users cannot bypass Nginx. If your backend application is containerized, avoid publishing it publicly with 0.0.0.0:PORT. Bind it locally: ports: - "127.0.0.1:8080:80" Or keep it on a private Docker network and proxy to it through Nginx. Troubleshooting Authelia container keeps restarting Check logs: docker logs authelia --tail200 Validate config: cd /opt/authelia docker compose down docker run --rm \ -v /opt/authelia/config:/config \ -v /opt/authelia/data:/data \ -v /opt/authelia/secrets:/secrets:ro \ authelia/authelia:latest \ authelia config validate --config /config/configuration.yml Common causes: Bad YAML indentation Wrong domain in session cookie Missing storage encryption key Invalid users_database.yml Unreadable secret files Invalid notification configuration Login works, but redirect back to app fails Check: session: cookies: - domain: example.com authelia_url: https://auth.example.com default_redirection_url: https://app.example.com The cookie domain should normally be the parent domain, such as: example.com not: auth.example.com when protecting multiple subdomains. Nginx returns 500 error Test Nginx config: nginx -t Check logs: tail -n 100 /var/log/nginx/error.log Make sure this endpoint is reachable locally: curl -I http://127.0.0.1:9091/api/authz/auth-request App is accessible without Authelia The app may be exposed directly. Check listening ports: ss -tulpn If your app is listening publicly, change it to listen only on localhost or a private Docker network. Bad: 0.0.0.0:8080 Better: 127.0.0.1:8080 TOTP setup email or password reset does not work If you are using filesystem notification mode, check: cat /opt/authelia/data/notification.txt For production, configure SMTP. Example Final File Layout /opt/authelia/ ├── docker-compose.yml ├── config/ │ ├── configuration.yml │ └── users_database.yml ├── data/ │ ├── db.sqlite3 │ └── notification.txt └── secrets/ ├── jwt_secret ├── session_secret └── storage_encryption_key Minimal Production Checklist Before considering the deployment complete: DNS records point to the VPS. Firewall allows only needed ports. Docker is installed and enabled. Authelia is bound to 127.0.0.1:9091. Nginx serves auth.example.com over HTTPS. app.example.com redirects unauthenticated users to Authelia. TOTP enrollment works. Access rules use default_policy: deny. SMTP notification is configured for production. Certbot renewal dry run passes. /opt/authelia is backed up securely. Direct backend app access is blocked. Recommended Next Step For a production hosting environment, the next improvement would be replacing the file user backend with LDAP or another centralized identity source, and replacing SQLite with PostgreSQL if you expect heavier use, multiple administrators, or more advanced identity-provider features. Authelia supports file and LDAP authentication backends, and supports local SQLite, MySQL, and PostgreSQL storage backends. Conclusion You now know how to deploy Authelia on Debian VPS.

Rad Web Hosting Blog

Tag: caddy

🚀 How to Deploy Coolify on Ubuntu VPS

Easily Install and Run Postal Email Platform on Ubuntu VPS (5 Minute Guide)

Self-Hosting Easypanel and n8n on Ubuntu VPS

Services

Categories

Recent Posts

Save on VPS Hosting!

We’re Social!

Rad Web Hosting Blog