Authelia on VPS: Installation, Configuration, and Maintenance

Installing Authelia on a VPS, configuring it, and subsequently maintaining it is an effective way to enhance the security of your web applications and services through a centralized authentication system and two-factor verification, deployed on your own virtual server.

In a world where data security is becoming critically important, the use of reliable authentication systems is not a whim, but a necessity. Authelia is a powerful solution for implementing Single Sign-On (SSO) and Two-Factor Authentication (2FA) in front of your web applications. Deployed on your own VPS, Authelia allows you to fully control the authentication process, protecting access to services such as Nextcloud, Gitea, Grafana, or any other resource accessible via a reverse proxy.

In this article, we will delve into what Authelia is, why it's needed, its system requirements, and how to perform a step-by-step installation on a VPS using Docker and Docker Compose. We will also cover integration with popular reverse proxies like Nginx and Caddy, HTTPS configuration, backup and update procedures, and help you choose the optimal VPS configuration for your workload. Our goal is to provide a comprehensive guide that will enable even novice system administrators to successfully deploy and maintain Authelia.

What is Authelia and why is it needed on a server?

Authelia is an open-source authentication solution that acts as a middleware layer in front of your web applications. Its primary function is to provide centralized access with Single Sign-On (SSO) and robust Two-Factor Authentication (2FA) support for services that do not inherently offer advanced verification methods. Essentially, Authelia acts as a gatekeeper, verifying user credentials before allowing access to the target application.

When a user attempts to access a protected application, Authelia intercepts the request, redirects the user to its login page where they enter their username and password, and then, if required, completes a second factor of authentication (e.g., via a TOTP app or email). After successful authentication, Authelia sets a session cookie and redirects the user to the original application, granting them access. This allows you to protect numerous services using a single set of credentials and a unified security policy.

Authelia self-hosted usage scenarios on a VPS

Deploying Authelia on a VPS opens up broad possibilities for enhancing the security of your infrastructure. Here are a few typical scenarios:

• Protecting internal web applications: If you have self-hosted services such as Nextcloud for cloud storage, Gitea for version control, Grafana for monitoring, Portainer for Docker container management, or even a simple admin panel for your website, Authelia can add a robust authentication layer to them.
• Access unification: Instead of managing accounts in each application separately, Authelia allows you to centralize user management (e.g., via LDAP or a YAML file), simplifying administration and improving user experience through SSO.
• Enhanced security with 2FA: Many internal applications do not offer 2FA or have limited options. Authelia adds support for TOTP (Time-based One-Time Password) or U2F (Universal 2nd Factor), as well as email authentication, significantly increasing protection against unauthorized access.
• API protection: Authelia can be used to protect API interfaces, requiring authentication before accessing data or functions.

Advantages of Authelia Docker on a VPS

Using Docker to install Authelia on a VPS brings several significant advantages:

• Isolation: Authelia runs in an isolated container, not affecting other services on your VPS. This reduces dependency conflicts and simplifies management.
• Portability: Containers are easy to move between different environments or VPS servers.
• Reproducibility: You can always be sure that Authelia will work identically in any Docker environment.
• Ease of deployment: Docker Compose allows you to define the entire Authelia infrastructure (the service itself, the database) in a single file, which significantly simplifies Authelia installation and management.
• Easy updates: Updating Authelia involves updating the Docker image and restarting the container.

By choosing containerization, you get a flexible, secure, and manageable solution for centralized authentication on your own server.

System Requirements and Pre-installation Preparation for Authelia

Before proceeding with the Authelia installation, it's crucial to ensure that your VPS meets the minimum system requirements and to perform a series of preliminary configurations. This will ensure stable and secure operation of the service.

Operating System and VPS Hardware Resources

• Operating System: Authelia, as a Docker container, can run on any Linux distribution that supports Docker. LTS (Long Term Support) versions of server distributions are recommended, such as:
  • Ubuntu 22.04 LTS or newer
  • Debian 11 (Bullseye) or newer
  • CentOS Stream 8/9
  Ensure that the system is updated to the latest version and all necessary packages are installed.
• Processor (CPU): For most Authelia use cases, 1 vCPU is sufficient. For a very large number of users (hundreds of simultaneous authentications) or integration with heavy LDAP directories, 2 vCPUs may be required.
• Random Access Memory (RAM): Authelia itself consumes little RAM, about 50-100 MB. However, for stable operation of the entire system (OS, Docker daemon, Authelia, as well as other services on the VPS), a minimum of 1 GB RAM is recommended. Optimally, 2 GB will provide a buffer for caching and peak loads.
• Disk Space: Authelia does not require much space. For Authelia itself and its database (SQLite by default or a small PostgreSQL), 5-10 GB is sufficient. However, for the operating system, Docker images, and logs, a minimum of 25-50 GB of SSD storage is recommended. NVMe drives will provide better performance.

Pre-installation of Docker and Docker Compose

Authelia is designed to run in Docker containers, so installing Docker Engine and Docker Compose is a mandatory step.

Docker Engine Installation

For Ubuntu/Debian, execute the following commands:

sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group to avoid using sudo with every Docker command:

sudo usermod -aG docker $USER
newgrp docker

Verify Docker installation:

docker run hello-world

Docker Compose Installation

In modern Docker versions, Docker Compose is installed as a plugin to Docker (docker-compose-plugin), as shown above. If you are using an older Docker version or want to install Docker Compose as a standalone executable, you can do so as follows:

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Verify Docker Compose installation:

docker compose version

Domain Name and DNS Record Configuration

For Authelia and reverse proxy to work correctly with HTTPS, you will need:

1. Domain Name: Register a domain name if you don't have one yet.
2. DNS Records: Create the following A-records with your DNS provider, pointing to your VPS's IP address:
   • auth.yourdomain.com (for Authelia)
   • app1.yourdomain.com (for the first protected application)
   • app2.yourdomain.com (for the second protected application)
   • And so on for each application you plan to protect.
   Ensure these records are set up and have propagated (which may take up to several hours).

Mail Server for 2FA and Password Reset

Authelia uses email to send 2FA codes (if this method is chosen) and password reset links. You will need access to an SMTP server. This can be:

• External SMTP provider: SendGrid, Mailgun, AWS SES, Gmail SMTP (with limitations). This is the simplest and most reliable option.
• Your own mail server: If you already have your own mail server on the VPS.

Prepare your SMTP credentials (host, port, username, password), as they will be needed when configuring Authelia.

After completing all these steps, your VPS will be ready for Authelia installation.

Step-by-Step Authelia Installation on a VPS using Docker Compose

Now that your VPS is prepared, we can proceed with the Authelia installation. We will use Docker Compose for convenient deployment of Authelia along with its database.

1. Creating the Working Directory and Configuration Files

Create a directory for your Authelia project on the VPS. For example, in the user's home directory:

mkdir -p ~/authelia
cd ~/authelia

In this directory, we will create two main files: docker-compose.yml for defining Docker services and configuration.yml for Authelia settings.

2. The docker-compose.yml File

This file describes which Docker images will be run, how they will interact, and what resources they will use. For Authelia, we will need the Authelia service itself and a database to store user data (by default, Authelia can use SQLite, but for production, PostgreSQL or MySQL is recommended). In our example, we will use SQLite for simplicity, which is ideal for small installations.

Create the docker-compose.yml file:

nano docker-compose.yml

And insert the following content:

version: "3.8"

services:
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    restart: unless-stopped
    volumes:
      - ./config:/config # Mapping the configuration directory
    environment:
      - TZ=Europe/Moscow # Set your timezone
    ports:
      - "9091:9091" # Port on which Authelia will listen for requests
    networks:
      - authelianet # Network for interaction with the reverse proxy

networks:
  authelianet:
    # external: true # If you want to use an existing external Docker network,
                     # for example, for your reverse proxy.
                     # If the reverse proxy also runs via Docker Compose in the same directory,
                     # then an internal network can be used.
                     # For simplicity, we'll keep it internal for now.

Explanations:

• image: authelia/authelia:latest: Uses the latest stable version of the Authelia image.
• volumes: - ./config:/config: Maps the local config directory (which we will create) inside the container to /config, where Authelia looks for its configuration files.
• ports: - "9091:9091": Publishes container port 9091 to host port 9091. This port will be used by your reverse proxy to communicate with Authelia.
• networks: - authelianet: Defines an internal Docker network for Authelia. If your reverse proxy also runs in Docker and needs to access Authelia by service name, ensure they are in the same Docker network (or use external: true and specify the name of an existing network).

3. The configuration.yml File (Basic Configuration)

This is the main Authelia configuration file. It defines users, domains, policies, SMTP settings, and much more. Create the config directory and the configuration.yml file inside it:

mkdir -p ~/authelia/config
nano ~/authelia/config/configuration.yml

Insert the following basic template. Replace yourdomain.com with your actual domain and fill in the SMTP data.

# Documentation: https://www.authelia.com/configuration/
---
log:
  level: debug # Change to 'info' or 'warn' for production

server:
  host: 0.0.0.0
  port: 9091

# Database access settings (SQLite by default)
authentication_backend:
  file:
    path: /config/users_database.yml # File with users and passwords (see below)

access_control:
  default_policy: deny # Deny by default if not explicitly allowed
  rules:
    # Allow access to Authelia UI without authentication (for the login page itself)
    - domain: auth.yourdomain.com
      policy: bypass
    # Protect all subdomains of yourdomain.com, except auth.yourdomain.com
    - domain: "*.yourdomain.com"
      policy: two_factor
      subject: "group:admins" # Only users from the 'admins' group
      # subject: "user:john.doe" # Or a specific user

session:
  secret: # Generated below
  domain: yourdomain.com # Your main domain
  name: authelia_session

# Settings for two-factor authentication via email
notifier:
  smtp:
    host: smtp.your_email_provider.com # E.g., smtp.sendgrid.net or smtp.gmail.com
    port: 587 # Or 465 for SSL
    username: your_smtp_username
    password: your_smtp_password
    sender: Authelia 
    disable_starttls: false # true if port 465 (SSL)

# Settings for 2FA via TOTP
totp:
  issuer: Authelia

# Settings for secret generation
jwt_secret: # Generated below

# Settings for data storage (SQLite)
storage:
  local:
    path: /config/db.sqlite3 # Path to the SQLite database file

regulation:
  max_retries: 3
  find_time: 1m
  ban_time: 5m

duo_api:
  disable: true # Disable Duo Security if not used

webauthn:
  disable: true # Disable WebAuthn if not used
  # display_name: Authelia
  # attestation_conveyance_preference: "none"
  # user_verification: "preferred"
  # challenge_timeout: "60s"
  # rp_id: yourdomain.com
  # rp_origin: https://auth.yourdomain.com

Important fields for configuration:

• log.level: Set to debug during setup, then info for production.
• access_control.rules: Defines which domains and how they will be protected. default_policy: deny is a good security practice.
• session.secret and jwt_secret: These are critically important secrets. They need to be generated.
• notifier.smtp: Fill in your SMTP server details.
• storage.local.path: Path to the SQLite database file.

4. Generating Secrets and Passwords

Long random strings are required for session.secret and jwt_secret. You will also need hashed passwords for users.

Generating Authelia Secrets

Authelia provides a utility to generate these secrets. Run a temporary Authelia container for this:

docker run --rm authelia/authelia:latest authelia crypto rand --size 64 --numeric --alphanumeric # For session_secret
docker run --rm authelia/authelia:latest authelia crypto rand --size 64 --numeric --alphanumeric # For jwt_secret

Copy the generated strings and paste them into your configuration.yml under the corresponding session.secret and jwt_secret fields.

Generating Hashed Passwords for Users

Authelia stores passwords as hashes. Use the same utility to generate hashes:

docker run --rm authelia/authelia:latest authelia crypto hash generate --password 'Your_Password'

Replace 'Your_Password' with your desired password. Copy the generated hash.

Now, create the users_database.yml file in the ~/authelia/config/ directory to define users and their groups:

nano ~/authelia/config/users_database.yml

Example content:

users:
  john.doe:
    displayname: John Doe
    password: '$argon2id$v=19$m=65536,t=3,p=4$randomsalt$randomhash' # Insert the generated hash
    email: [email protected]
    groups:
      - admins
      - developers
  jane.doe:
    displayname: Jane Doe
    password: '$argon2id$v=19$m=65536,t=3,p=4$randomsalt$randomhash' # Insert the generated hash
    email: [email protected]
    groups:
      - developers

Replace password hashes and email addresses with your own. Ensure that the groups match those specified in access_control.rules.

5. Starting Authelia

Once all configuration files are created and populated, you can start Authelia using Docker Compose:

cd ~/authelia
docker compose up -d

The -d command runs containers in the background. Check the status of the containers:

docker compose ps

And check Authelia's logs to ensure it started without errors:

docker compose logs authelia

You should see messages about startup and initialization.

6. Initial Verification

At this stage, Authelia is running and listening on port 9091 of your VPS. You won't be able to access it directly from a browser, as it's designed to work through a reverse proxy. However, you can check its availability using curl on the server itself:

curl http://localhost:9091

You should receive the HTML code for Authelia's login page.

Now that Authelia Docker installation is complete, the next step will be to configure a reverse proxy to route traffic to Authelia and your protected applications, as well as to provide HTTPS.

Integrating Authelia with a Reverse Proxy (Nginx, Caddy) and HTTPS

Authelia acts as a middleware layer, which means it needs a reverse proxy to direct requests to it and then to your protected applications. The reverse proxy is also responsible for SSL/TLS termination (HTTPS) and routing based on domain names. We will cover configuration with Nginx and Caddy — two popular solutions.

General Principles of Working with Reverse Proxy and Authelia

The operating principle is as follows:

1. The user requests app.yourdomain.com.
2. The reverse proxy intercepts the request.
3. The reverse proxy sends a request to Authelia's internal endpoint (usually /api/verify) to check if the user is authenticated.
4. If Authelia reports that the user is not authenticated, the reverse proxy redirects the user to Authelia's login page (auth.yourdomain.com).
5. After successful authentication, Authelia sets a session cookie, and the reverse proxy grants access to app.yourdomain.com.

HTTPS is mandatory for Authelia's secure operation, as it protects credentials and session cookies from interception.

1. Nginx Configuration for Authelia

Nginx is a powerful and widely used reverse proxy. Ensure that Nginx is installed on your VPS. If not:

sudo apt update
sudo apt install nginx

Creating Nginx Configuration Files

We will create two configuration files: one for Authelia and one for the protected application. First, disable the default Nginx site:

sudo rm /etc/nginx/sites-enabled/default

Configuration file for Authelia (auth.yourdomain.com.conf):

Create the file in /etc/nginx/sites-available/:

sudo nano /etc/nginx/sites-available/auth.yourdomain.com.conf

Insert the following content, replacing yourdomain.com with your domain:

server {
    listen 80;
    listen [::]:80;
    server_name auth.yourdomain.com;

    # Redirect to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name auth.yourdomain.com;

    # Replace with paths to your SSL certificates
    # Obtain them using Certbot (see below)
    ssl_certificate /etc/letsencrypt/live/auth.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.yourdomain.com/privkey.pem;

    # Additional SSL settings
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1h;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers off;
    ssl_stapling on;
    ssl_stapling_verify on;
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    add_header X-XSS-Protection "1; mode=block";

    location / {
        proxy_pass http://127.0.0.1:9091; # Or Authelia service name if Nginx is in the same Docker network
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
        proxy_connect_timeout 60s;
    }
}

Configuration file for the protected application (app.yourdomain.com.conf):

Suppose you have an application running on http://127.0.0.1:8080. Create the file:

sudo nano /etc/nginx/sites-available/app.yourdomain.com.conf

Insert the following content:

server {
    listen 80;
    listen [::]:80;
    server_name app.yourdomain.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name app.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/app.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.yourdomain.com/privkey.pem;

    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1h;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers off;
    ssl_stapling on;
    ssl_stapling_verify on;
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    add_header X-XSS-Protection "1; mode=block";

    # Authelia authentication block
    location / {
        # If the request is not authenticated, Nginx will redirect to the Authelia page
        auth_request /authelia;
        error_page 401 = @authelia;

        # Pass headers with user information
        auth_request_set $user $upstream_http_x_authentik_username; # Replace with X-Authelia-User if using older versions or just Authelia
        auth_request_set $email $upstream_http_x_authentik_email; # Replace with X-Authelia-Email
        proxy_set_header Remote-User $user;
        proxy_set_header Remote-Email $email;

        proxy_pass http://127.0.0.1:8080; # Address of your application
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
        proxy_connect_timeout 60s;
    }

    # Internal location for Authelia verification
    location /authelia {
        internal;
        proxy_pass http://127.0.0.1:9091/api/verify; # Or Authelia service name
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_pass_request_body off;
        proxy_pass_request_headers off;
        proxy_set_header Content-Length "";
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
        proxy_connect_timeout 60s;
    }

    # Redirect to Authelia UI on 401 error
    location @authelia {
        return 302 https://auth.yourdomain.com/?rd=$request_uri;
    }
}

Important: Replace http://127.0.0.1:8080 with the actual address of your application. If Nginx and Authelia are in the same Docker network, you can use http://authelia:9091 instead of http://127.0.0.1:9091.

Obtaining SSL Certificates with Certbot

Certbot is a tool for automatically obtaining and renewing free SSL/TLS certificates from Let's Encrypt.

sudo apt install certbot python3-certbot-nginx

Then, obtain certificates for all your domains (auth.yourdomain.com and app.yourdomain.com):

sudo certbot --nginx -d auth.yourdomain.com -d app.yourdomain.com

Certbot will automatically modify the Nginx configuration, adding paths to the certificates. After this, you may need to manually adjust some SSL settings if they were overwritten.

Activating Nginx Configuration

Create symbolic links to your configuration files in sites-enabled:

sudo ln -s /etc/nginx/sites-available/auth.yourdomain.com.conf /etc/nginx/sites-enabled/
sudo ln -s /etc/nginx/sites-available/app.yourdomain.com.conf /etc/nginx/sites-enabled/

Check the Nginx configuration for errors:

sudo nginx -t

If there are no errors, reload Nginx:

sudo systemctl reload nginx

2. Caddy Configuration for Authelia

Caddy is a modern reverse proxy that automatically manages HTTPS certificates with Let's Encrypt, significantly simplifying its configuration. Install Caddy by following the instructions on the official website (e.g., for Debian/Ubuntu):

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Creating the Caddyfile

Caddy's main configuration file is called Caddyfile. Create or edit it:

sudo nano /etc/caddy/Caddyfile

Insert the following content:

{
    # Global Caddy settings
    email [email protected] # For Let's Encrypt notifications
}

# Authelia UI
auth.yourdomain.com {
    reverse_proxy 127.0.0.1:9091
}

# Protected application
app.yourdomain.com {
    # Authelia authentication block
    # Replace authelia.yourdomain.com with the actual Authelia address
    # If Caddy and Authelia are in the same Docker network, use the service name: http://authelia:9091
    # If Authelia is on the host, then: http://127.0.0.1:9091
    # Important: Authelia must be accessible via HTTPS for Caddy if it's not on the same host without SSL.
    # For simplicity, we assume Authelia is accessible via HTTP on localhost:9091.
    
    # Authentication check
    handle {
        # Send a verification request to Authelia
        remote_auth http://127.0.0.1:9091/api/verify {
            # Pass headers if Authelia supports them (X-Authelia-User, X-Authelia-Groups)
            # Depending on Authelia version and your configuration, headers may differ
            # Check Authelia documentation for current headers
            # forward_auth_response_headers X-Authelia-User X-Authelia-Groups X-Authelia-Email
        }

        # If authentication passed, proxy to the application
        reverse_proxy 127.0.0.1:8080 # Address of your application
    }

    # Redirect to Authelia UI on 401 error
    handle_errors {
        @401 {
            expression `{http.error.status_code} == 401`
        }
        rewrite @401 https://auth.yourdomain.com/?rd={http.request.uri}
        respond "{http.error.status_code} {http.error.status_text}" {
            close
        }
    }
}

Important: Replace yourdomain.com with your domain and http://127.0.0.1:8080 with the address of your application. If Caddy and Authelia are in the same Docker network, use http://authelia:9091.

Verifying and Starting Caddy

Check the Caddy configuration:

sudo caddy validate --config /etc/caddy/Caddyfile

If the configuration is correct, reload Caddy:

sudo systemctl reload caddy

Caddy will automatically obtain and configure HTTPS certificates for your domains.

Now that the reverse proxy is configured, you can try to access app.yourdomain.com. You should be redirected to auth.yourdomain.com to log in. After successful authentication, you will gain access to your application.

Authelia Maintenance: Backups, Updates, and Monitoring

Deploying Authelia is just the beginning. To ensure stable, secure, and up-to-date system operation, it is necessary to regularly perform backups, update components, and monitor its status. A self-managed VPS implies that all responsibility for these processes lies with you.

Authelia Configuration and Data Backup Strategies

Authelia backup includes two main components:

1. Configuration files: configuration.yml, users_database.yml (and any others if you use them).
2. Database: If you are using SQLite (db.sqlite3), it's just a single file. If PostgreSQL or MySQL, you need to use tools for backing up those databases.

Backup Recommendations:

• Automation: Set up daily or weekly automatic backups using cron scripts.
• Storage: Store backups on separate storage, distinct from your VPS (e.g., S3-compatible storage, Dropbox, Google Drive, another server). This will protect data in case of a complete VPS failure.
• Encryption: Always encrypt backups, especially if they are stored on external services.
• Testing: Regularly test the ability to restore from backups to ensure their integrity.

Example Backup Script (for SQLite):

Create the backup_authelia.sh file in ~/authelia/:

#!/bin/bash

# Path to Authelia directory
AUTHELIA_DIR="/home/youruser/authelia"
# Directory for storing backups
BACKUP_DIR="/var/backups/authelia"
# Backup file name
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/authelia_backup_${TIMESTAMP}.tar.gz"
# Secret key for encryption (replace with your own)
ENCRYPTION_PASS="YourVeryStrongEncryptionPassword" 

mkdir -p "$BACKUP_DIR"

echo "Stopping Authelia for a consistent backup..."
docker compose -f "$AUTHELIA_DIR/docker-compose.yml" stop authelia

echo "Creating configuration and database archive..."
tar -czf "$BACKUP_FILE" -C "$AUTHELIA_DIR/config" .

echo "Starting Authelia..."
docker compose -f "$AUTHELIA_DIR/docker-compose.yml" start authelia

echo "Encrypting backup..."
gpg --batch --passphrase "$ENCRYPTION_PASS" --symmetric "$BACKUP_FILE"
rm "$BACKUP_FILE" # Deleting unencrypted backup

echo "Authelia backup completed: ${BACKUP_FILE}.gpg"

# Deleting old backups (e.g., older than 7 days)
find "$BACKUP_DIR" -name "authelia_backup_*.tar.gz.gpg" -mtime +7 -delete
echo "Old backups deleted."

Make the script executable: chmod +x ~/authelia/backup_authelia.sh. Then add it to cron for regular execution (e.g., daily at 3 AM):

crontab -e

Add the line:

0 3 * * * /bin/bash /home/youruser/authelia/backup_authelia.sh >> /var/log/authelia_backup.log 2>&1

Authelia Docker Image Update Process

Regular Authelia updates are important for receiving new features, bug fixes, and most importantly, addressing security vulnerabilities.

Since Authelia is deployed via Docker Compose, the update process is very simple:

cd ~/authelia
docker compose pull authelia # Downloads the latest version of the Authelia image
docker compose up -d --remove-orphans # Recreates the container with the new image and removes old ones

It is recommended to check the official Authelia documentation before major updates to ensure there are no critical configuration changes.

Monitoring Authelia Status and Logs

Monitoring allows for timely identification and response to issues. Here's what you need to track:

• Authelia Logs: Regularly review Authelia logs for errors or warnings.

docker compose logs authelia -f # Real-time log viewing
docker compose logs authelia --tail 100 # Last 100 lines

• Container Status: Ensure that the Authelia container is running.

docker compose ps

• Authelia Availability: Use external monitoring (e.g., UptimeRobot) to check the availability of your auth.yourdomain.com domain.
• VPS Resource Monitoring: Track CPU, RAM, disk space, and network traffic usage. Tools like Netdata or Prometheus/Grafana are excellent for this.

Regular execution of these procedures will keep your Authelia up-to-date and operational, ensuring continuous protection for your services.

Choosing the Optimal VPS Configuration for Authelia under Real Workload

Choosing the right VPS configuration for Authelia depends on several key factors, including the number of users, authentication frequency, the number of protected applications, and the presence of other services on the same VPS. Authelia itself is quite lightweight, but the overall infrastructure (OS, Docker, reverse proxy, database) requires a certain resource buffer.

Factors Affecting Authelia Load

• Number of active users: The more users who regularly authenticate, the higher the load.
• Authentication frequency: If users frequently log in and out of protected applications, Authelia will be more active.
• 2FA method: Using an external SMTP server for email codes can be more resource-intensive than TOTP.
• LDAP/AD integration: If Authelia is integrated with an external LDAP server, this may add a small load, but it's usually negligible on Authelia's side.
• Co-location of services: If the reverse proxy itself, protected applications, or other services are running on the same VPS, their resource requirements must be summed up.

RAM, CPU, SSD Recommendations

The recommendations below apply only to Authelia and its required reverse proxy. If you plan to host other services on the VPS, their resource requirements should be added to these values.

Authelia Use Case	vCPU (cores)	RAM (GB)	SSD (GB)	Approximate VPS Cost (per month)
Personal Use / Testing (1-5 users)	1	1	25-50	$5 - $10
Small Business / Small Team (5-20 users)	1-2	2	50-80	$10 - $20
Medium Business / Active Use (20-100 users)	2	4	80-160	$20 - $40
Large Organization / High Load (100+ users)	4+	8+	160+	$40+

Table Explanations:

• vCPU: For most Authelia scenarios, one core is sufficient. Two cores provide a performance buffer for peak loads and for the reverse proxy. For very large loads or integration with heavy LDAP directories, 4+ cores may be required.
• RAM: 1 GB RAM is the absolute minimum for the operating system, Docker, and Authelia. 2 GB is a comfortable minimum for small to medium installations. 4 GB or more provides excellent performance and a buffer for caching, especially if other services are running on the VPS.
• SSD: Authelia does not require much space, but for the operating system, Docker images, logs, and potential backups, 25 GB is recommended. NVMe drives significantly improve overall system performance.
• Approximate VPS Cost: Prices can vary significantly depending on the provider, region, and additional options (e.g., managed VPS). The figures provided are approximate benchmarks for quality VPS with good performance.

Recommendations for Choosing a VPS Provider:

When choosing a VPS for Authelia, pay attention to the following aspects:

1. Reliability and Uptime: Choose providers with a high reputation and guaranteed uptime (99.9% and above).
2. Disk Performance: NVMe SSDs will significantly speed up Docker and database operations.
3. Network Connectivity: Stable and fast network connectivity is important for quick access to Authelia and protected applications.
4. Support: Availability of prompt technical support, especially if you choose a self-managed VPS.
5. Geographical Location: Place the VPS closer to your primary users to reduce latency.
6. Scalability: Ensure that you can easily increase the resources (CPU, RAM, disk) of your VPS as your needs grow.

For most users starting with Authelia, a VPS with 2 vCPUs, 2-4 GB RAM, and 50-80 GB NVMe SSD will be more than sufficient for comfortable and stable operation. As needs grow, resources can always be scaled, which is one of the key advantages of using virtual servers.

Common Problems During Authelia Installation and Configuration and Their Solutions

Various difficulties may arise during Authelia installation and configuration on a VPS. Knowing common problems and how to solve them will significantly simplify the debugging process.

1. Errors in configuration.yml

Problem: Authelia does not start or behaves unpredictably, with YAML parsing errors or incorrect parameters visible in the logs.

Cause: Incorrect YAML syntax (indentation, colons, case), typos in parameters, missing required fields.

Solution:

• Syntax Check: Use online YAML validators (e.g., YAML Lint) or the yamllint tool to check the file for syntax errors.
• Careful Log Reading: Authelia logs (docker compose logs authelia) are usually very informative and point to the specific line or section where an error occurred.
• Official Documentation: Always refer to the official Authelia documentation for current parameters and their values.
• Logging Level: Set log.level: debug in configuration.yml to get the most detailed error information.

2. Reverse Proxy Issues (Nginx/Caddy)

Problem: Unable to access Authelia UI or the protected application, 502 Bad Gateway, 403 Forbidden errors, or an infinite redirect.

Cause: Incorrect Nginx/Caddy configuration, SSL certificate issues, Authelia inaccessible to the reverse proxy.

Solution:

• Check Reverse Proxy Logs:
  • For Nginx: sudo tail -f /var/log/nginx/error.log
  • For Caddy: sudo journalctl -u caddy -f
  These logs will indicate issues with proxying or SSL.
• Authelia Availability: Ensure that Authelia is listening on the correct port (9091) and is accessible to the reverse proxy. If Nginx/Caddy and Authelia are in different Docker networks, or Nginx/Caddy is running on the host, ensure that port 9091 is open and there are no firewalls blocking traffic. Check with the command curl http://127.0.0.1:9091 on the VPS.
• SSL Certificates: Ensure that Let's Encrypt certificates for auth.yourdomain.com and app.yourdomain.com (or other domains) are correctly obtained, not expired, and properly specified in the reverse proxy configuration.
• Authentication Rules: Verify that the access_control.rules in configuration.yml match the domains you are trying to protect.
• Headers: Ensure that the reverse proxy correctly passes X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers to Authelia, as it uses them for proper operation.

3. Incorrect Operation of Mail Server for 2FA or Password Reset

Problem: Users are not receiving 2FA codes or password reset links.

Cause: Incorrect SMTP settings in configuration.yml, network or firewall issues, blocking by mail provider.

Solution:

• Check Authelia Logs: Authelia will log errors related to email sending.
• SMTP Settings: Carefully check notifier.smtp in configuration.yml: host, port, username, password, sender. Ensure that disable_starttls is set correctly (false for port 587, true for port 465).
• Test SMTP: Try sending a test email from the VPS using curl or swaks utility to rule out network or firewall issues.
• Spam Filters: Check the recipient's "Spam" folder. Authelia emails might be blocked.
• Provider Limits: Some mail providers (especially free ones) have strict limits on the number of emails that can be sent.

4. Permission Issues

Problem: Authelia cannot write data to the database (SQLite) or read configuration files, "permission denied" errors.

Cause: Incorrect permissions for the ~/authelia/config directory or files within it.

Solution:

• Permissions for config directory: Ensure that the user under which the Authelia Docker container runs has read and write permissions to the ~/authelia/config directory. Usually, it is sufficient for the directory owner to be your user, and permissions to be 755 for directories and 644 for files.

sudo chmod -R 755 ~/authelia/config
sudo chmod 644 ~/authelia/config/*.yml ~/authelia/config/*.sqlite3

• Owner: If Authelia is run by a different user inside the container (which is rare for a standard image), you might need to change the file owner.

5. Session and Cookie Issues

Problem: Users are constantly redirected to the login page, even after successful authentication.

Cause: Incorrectly configured session.domain in configuration.yml, browser cookie blocking, or mismatch between HTTPS and HTTP.

Solution:

• session.domain: Ensure that session.domain is set to your main domain (e.g., yourdomain.com), not a subdomain (auth.yourdomain.com). This allows cookies to be accessible across all subdomains.
• HTTPS: Ensure that all traffic goes through HTTPS. Authelia requires a secure context for session cookies.
• Clear Browser Cookies: Try clearing cookies and cache in your browser.
• session.secret: Ensure that session.secret is long and random. Changing the secret will invalidate all active sessions.

A systematic approach to debugging, starting with logs and configuration checks, usually allows for quickly finding and resolving most issues. Don't forget about the Authelia community and their GitHub repository, where you can find answers to many questions.

Conclusion

Authelia on a VPS provides a powerful and flexible solution for centralized authentication and two-factor protection of your self-hosted web applications. By following the detailed instructions for installation via Docker Compose, reverse proxy configuration, and regular maintenance, you can significantly enhance the security of your infrastructure.

Choosing the optimal VPS configuration on Valebyte.com will ensure stable Authelia operation even under significant load, while regular backups and updates guarantee the long-term reliability of your authentication system.