# Security and Secrets

_Last updated: 2025-12-13_

This document outlines the security mechanisms and best practices for managing secrets within this infrastructure.

## Authentication

### Authelia

The primary authentication mechanism is [Authelia](https://www.authelia.com/), an open-source authentication and authorization server. Authelia provides Single Sign-On (SSO) for most web-facing services.

-   **How it works:** Traefik is configured to use Authelia as a forward authentication middleware. When a user tries to access a protected service, Traefik forwards the request to Authelia. If the user is not authenticated, Authelia presents a login page. Upon successful authentication, Authelia sets the `Remote-User` header in the request and forwards it to the backend service.
-   **Configuration:** Authelia's configuration is managed in its own `configuration.yml` file.
-   **Middleware:** Two Authelia middleware configurations are used in Traefik:
    -   `authelia-brewery`
    -   `authelia-fails`

### Application-level Authentication

Some applications manage their own authentication, separate from Authelia. These services are typically not behind the Authelia middleware in Traefik.

## Secret Storage

Secrets, such as API keys and database passwords, are primarily stored in `.env` files within each service's directory.

-   **.env files:** These files are used to populate environment variables in the `docker-compose.yml` files. For example, `books_webv2/.env` contains the database credentials for the Books V2 application.
-   **docker-compose.yml:** Some secrets are stored directly in the `docker-compose.yml` files. This is less secure and should be avoided where possible.

### ⚠️ **WARNING:**
-   **Do not commit `.env` files to Git repositories.** These files should be listed in the `.gitignore` file.
-   **Be careful when sharing `docker-compose.yml` files.** They may contain sensitive information.

## SSL/TLS Configuration

-   **Traefik:** Traefik automatically handles SSL/TLS termination for all web services. It is configured to use Let's Encrypt to automatically provision and renew SSL certificates.
-   **Entry Points:** The `websecure` entry point on port 443 is used for all HTTPS traffic. The `web` entry point on port 80 redirects all HTTP traffic to HTTPS.

## Network Security

-   **Firewall:** The network's edge router/firewall should be configured to only allow inbound traffic on ports `80` and `443`, and forward this traffic to the Traefik server (`192.168.12.3`).
-   **Exposed Ports:** Most services do not expose their ports directly to the host machine. They are only accessible through the `traefik_proxy` network. Only services that require direct access (e.g., `sftp`) should have their ports exposed.
-   **Docker Networks:** Services are isolated using Docker networks. This limits the ability of a compromised container to access other services on the host.

## Best Practices

-   **Rotate credentials regularly:** API keys, database passwords, and other secrets should be rotated on a regular basis.
-   **Use strong, unique passwords:** Avoid using default or weak passwords.
-   **Keep software up to date:** Regularly update all services and the underlying host operating system to patch security vulnerabilities. Watchtower is used to automatically update Docker containers.
-   **Principle of least privilege:** Each service should only have the permissions it needs to function. For example, database users should only have access to the databases they need.