docs: Update README with required setup steps and configuration details for Authelia v4.38+

README.md

@@ -11,6 +11,7 @@ The core idea is to manage media libraries (movies, TV shows, music), automate d
   - [Architecture Overview](#architecture-overview)
   - [Features](#features)
   - [Prerequisites](#prerequisites)
+  - [Required Setup Steps](#required-setup-steps)
   - [Quick Start Guide](#quick-start-guide)
   - [Configuration (`.env` Variables)](#configuration-env-variables)
       - [Core System \& Paths](#core-system--paths)
@@ -89,9 +90,45 @@ This stack includes the following services, categorized for clarity:
 *   **Tailscale Account:** Required for remote access. [Sign up here](https://tailscale.com/login).
 *   **(Optional) SELinux:** If enabled, see [Troubleshooting](#selinux-socket-permissions).
 
+## Required Setup Steps
+
+These steps are **mandatory** for a working installation. Without properly completing these, the stack will not function correctly.
+
+1. **⚠️ Required: System User Information**
+   - Set `USER_ID` and `GROUP_ID` in `.env` (run `id -u` and `id -g` to get yours)
+   - Incorrect values will cause permission errors with mounted volumes
+
+2. **⚠️ Required: Directory Paths**
+   - Set `CONFIG_ROOT` (where service configurations will be stored)
+   - Set `DATA_ROOT` (where your media libraries will be stored)
+   - Set `DOWNLOAD_ROOT` (must be on same filesystem as DATA_ROOT for hardlinks)
+
+3. **⚠️ Required: Tailscale Configuration**
+   - Create a Tailscale account at [tailscale.com](https://tailscale.com)
+   - Generate an Auth Key in the [Tailscale Admin Console](https://login.tailscale.com/admin/settings/keys)
+   - Set `TAILSCALE_AUTHKEY` in `.env`
+   - Set `TAILSCALE_TAILNET_DOMAIN` to your Tailnet domain (e.g., `your-name.ts.net`)
+
+4. **⚠️ Required: Security Credentials**
+   - Generate four strong random secrets using `openssl rand -hex 32`:
+     ```bash
+     echo "AUTHELIA_JWT_SECRET=$(openssl rand -hex 32)"
+     echo "AUTHELIA_SESSION_SECRET=$(openssl rand -hex 32)"
+     echo "AUTHELIA_STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32)"
+     echo "AUTHELIA_REDIS_PASSWORD=$(openssl rand -hex 32)"
+     ```
+   - Add these to your `.env` file as shown
+   
+5. **⚠️ Required: Create Admin Password**
+   - Generate a password hash for Authelia:
+     ```bash
+     docker run --rm authelia/authelia:latest authelia hash-password 'your_secure_password'
+     ```
+   - Replace the example hash in `authelia/users_database.yml` with your generated hash
+
 ## Quick Start Guide
 
-This guide gets the core stack running quickly. **Read the full [Configuration](#configuration-env-variables) section afterwards for details.**
+After completing all [Required Setup Steps](#required-setup-steps) above, follow these steps to get up and running:
 
 1. **Clone Repository:**
    ```bash
@@ -99,41 +136,46 @@ This guide gets the core stack running quickly. **Read the full [Configuration](
    cd docker-compose-nas
    ```
 
-2.  **Create `.env` File:**
+2. **Configure Environment:**
    ```bash
+   # Create an .env file from the example
    cp .env.example .env
+   
+   # Edit the .env file and fill in ALL required values
+   nano .env
    ```
 
-3.  **Critical `.env` Edits:** Open `.env` and set **at minimum**:
-    *   `USER_ID` & `GROUP_ID`: Run `id -u` and `id -g` on your host to find these.
-    *   `TIMEZONE`: Your local timezone (e.g., `Asia/Manila`).
-    *   `TAILSCALE_AUTHKEY`: Generate an auth key in your [Tailscale Admin Console](https://login.tailscale.com/admin/settings/keys).
-    *   `TAILSCALE_TAILNET_DOMAIN`: Your unique Tailnet domain (e.g., `your-name.ts.net`).
-    *   `AUTHELIA_JWT_SECRET`, `AUTHELIA_SESSION_SECRET`, `AUTHELIA_STORAGE_ENCRYPTION_KEY`, `AUTHELIA_REDIS_PASSWORD`: **Generate unique, strong secrets** for these (e.g., using `openssl rand -hex 32`). **Do not use the examples!**
-
-4.  **Set Authelia Admin Password:**
-    *   Generate a password hash (replace `'your_secure_password'`):
+3. **Configure Authelia Admin:**
    ```bash
+   # Generate a password hash
    docker run --rm authelia/authelia:latest authelia hash-password 'your_secure_password'
-        ```
-    *   Copy the **entire output hash** (starting with `$argon2id...`).
-    *   Open `authelia/users_database.yml` and replace the example `password:` value under `admin:` with your generated hash.
    
-5.  **Start the Stack:**
+   # Edit the users_database.yml with the generated hash
+   nano authelia/users_database.yml
+   ```
+
+4. **Start the Stack:**
    ```bash
    # Make helper script executable (if needed)
    chmod +x ./update-config.sh
+   chmod +x ./update-env.sh
+   
    # Start containers
    docker compose up -d
    ```
-    *(Wait for containers to download and start)*
 
-6.  **(Optional) Run Config Script:** This attempts to set API keys/URLs in *arr apps based on `.env`. May require manual adjustments in apps later.
+5. **Configure Service API Keys** (after stack is running):
    ```bash
+   # Optional: Run config script to set API keys
    ./update-config.sh
    ```
 
-7.  **Access:** Navigate to `https://<TAILSCALE_HOSTNAME>.<TAILSCALE_TAILNET_DOMAIN>/`. You should be redirected to the Authelia login. Use `admin` and the password you set in step 4. After login, you'll land on the Homepage dashboard at `/home`.
+6. **Access Your NAS:**
+   - Open `https://<TAILSCALE_HOSTNAME>.<TAILSCALE_TAILNET_DOMAIN>/`
+   - Log in with username `admin` and the password you set
+   - After login, you'll land on the Homepage dashboard at `/home`
+
+> ⚠️ **IMPORTANT:** If the stack fails to start, check the [Troubleshooting](#troubleshooting) section and verify you've properly completed all [Required Setup Steps](#required-setup-steps).
 
 ## Configuration (`.env` Variables)
 
@@ -355,24 +397,35 @@ If you are running Docker on a host with SELinux enabled (like Fedora, CentOS, R
 
 Authelia v4.38+ introduces significant changes to its configuration structure, particularly for session domains and authentication flows. This Docker Compose template has been updated to support these changes, making it easier to set up:
 
-1. **Centralized Configuration**: All required Authelia settings are defined in the `.env` file - you don't need to manually edit the Authelia YAML configuration.
+1. **Simplified Configuration**: The setup now uses a more reliable approach with wildcard domain matching (`*.ts.net`) that works properly with Tailscale domains. This eliminates environment variable interpolation issues that were causing errors in previous versions.
 
-2. **Domain Handling**: The system now uses wildcard domain matching (`*.ts.net`) to handle Tailscale domains, eliminating environment variable expansion issues that could cause errors like:
+2. **No Manual YAML Editing Required**: You don't need to edit the Authelia configuration file manually. The important settings are configured through environment variables in the Docker Compose setup.
+
+3. **Required Secret Variables**: You only need to set these four variables in your `.env` file:
+   - `AUTHELIA_JWT_SECRET`: Used for password reset tokens
+   - `AUTHELIA_SESSION_SECRET`: Used for session cookie encryption
+   - `AUTHELIA_STORAGE_ENCRYPTION_KEY`: Used for database encryption
+   - `AUTHELIA_REDIS_PASSWORD`: Used for Redis authentication
+
+   Generate strong random values for these with: `openssl rand -hex 32`
+
+4. **File Permissions Fixed**: The Authelia container now runs with your user ID and group ID, preventing permission issues when managing the configuration files with git or other tools.
+
+5. **Common Error Solutions**: If you encounter configuration errors like these:
    ```
    error decoding 'session.cookies[0].authelia_url': could not decode 'https://${APP_HOSTNAME}'
+   can't be specified at the same time: option 'domain' and option 'cookies'
    ```
+   The solution is already implemented in the updated configuration. No manual fixes needed.
 
-3. **Required Variables**: You only need to set these variables in your `.env` file:
-   - `AUTHELIA_JWT_SECRET`: For password reset tokens
-   - `AUTHELIA_SESSION_SECRET`: For session cookie encryption
-   - `AUTHELIA_STORAGE_ENCRYPTION_KEY`: For database encryption
-   - `AUTHELIA_REDIS_PASSWORD`: For Redis authentication
+If you need to make changes to the domain settings for some reason, edit `authelia/configuration.yml` and modify the `*.ts.net` wildcard pattern to match your specific domain. For most setups using Tailscale, the default configuration will work without any changes.
 
-   Generate these with: `openssl rand -hex 32`
+After making changes to the configuration, restart Authelia with:
+```bash
+docker compose restart authelia
+```
 
-4. **Domain Configuration**: Your Tailscale domain is automatically set using `APP_HOSTNAME=${TAILSCALE_HOSTNAME}.${TAILSCALE_TAILNET_DOMAIN}` in the `.env` file.
-
-If you still encounter issues, make sure your `TAILSCALE_TAILNET_DOMAIN` ends with `.ts.net` for proper domain matching, or edit `authelia/configuration.yml` to match your specific domain pattern.
+See the [Authelia documentation](https://www.authelia.com/configuration/session/introduction/) for more details on the v4.38+ configuration structure.
 
 ### Tailscale Issues
 

authelia/configuration.yml

@@ -1,14 +1,14 @@
 # Authelia Configuration File v4.38+
 # Documentation: https://www.authelia.com/configuration/
 
-# Server settings using the new 'address' format
+# Server settings
 server:
-  address: 'tcp://0.0.0.0:9091' # Listen on all interfaces, port 9091
+  address: 'tcp://0.0.0.0:9091'
 
 # Logging configuration
 log:
   level: info
-  format: text # or json
+  format: text
 
 # Session configuration for v4.38+
 session:
@@ -22,10 +22,11 @@ session:
     password: ${AUTHELIA_SESSION_REDIS_PASSWORD}
     database_index: 0
   cookies:
-    # Use the wildcard domain pattern to match all subdomains
-    - domain: ${AUTHELIA_SESSION_DOMAIN}
-      authelia_url: ${AUTHELIA_DEFAULT_REDIRECTION_URL}
-      default_redirection_url: ${AUTHELIA_DEFAULT_REDIRECTION_URL}
+    # Using a wildcard domain pattern - works for Tailscale domains
+    - domain: '*.ts.net'
+      authelia_url: 'https://tailscale-nas.ts.net'
+      default_redirection_url: 'https://tailscale-nas.ts.net/home'
+      same_site: lax
 
 # Regulation (brute force protection)
 regulation:
@@ -44,19 +45,20 @@ authentication_backend:
   file:
     path: /config/users_database.yml
     password:
-      algorithm: argon2id # Recommended hashing algorithm
+      algorithm: argon2id
       iterations: 1
-      memory: 1024 # MiB
+      memory: 1024
       parallelism: 8
       salt_length: 16
       key_length: 32
 
 # Access control rules
 access_control:
-  default_policy: deny # Deny access by default
+  default_policy: deny
   rules:
-    - domain: ${AUTHELIA_SESSION_DOMAIN}
-      policy: one_factor # Requires username/password
+    # This will match any Tailscale domain
+    - domain: '*.ts.net'
+      policy: one_factor
 
 # Notifier configuration
 notifier:
@@ -70,4 +72,4 @@ identity_validation:
 
 # Identity Providers
 identity_providers:
-  oidc: null # Explicitly disable OIDC
+  oidc: null

docker-compose.yml

@@ -47,16 +47,14 @@ services:
     volumes:
       - ${CONFIG_ROOT:-.}/authelia:/config:Z
     environment:
-      # Core secrets and keys
+      # Core secrets
       - AUTHELIA_JWT_SECRET=${AUTHELIA_JWT_SECRET}
       - AUTHELIA_SESSION_SECRET=${AUTHELIA_SESSION_SECRET}
       - AUTHELIA_STORAGE_ENCRYPTION_KEY=${AUTHELIA_STORAGE_ENCRYPTION_KEY}
       - AUTHELIA_SESSION_REDIS_PASSWORD=${AUTHELIA_REDIS_PASSWORD}
+      # Only environment variable needed for identity validation
       - AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET=${AUTHELIA_JWT_SECRET}
-      # Domain settings extracted from APP_HOSTNAME
-      - AUTHELIA_SESSION_DOMAIN=${APP_HOSTNAME}
-      - AUTHELIA_SERVER_DOMAIN=${APP_HOSTNAME}
-      - AUTHELIA_DEFAULT_REDIRECTION_URL=https://${APP_HOSTNAME}/home
+      # Timezone
       - TZ=${TIMEZONE}
     labels:
       - traefik.enable=true