diff --git a/docs/en/advanced.md b/docs/en/advanced.md index 89332bd..2a02e80 100644 --- a/docs/en/advanced.md +++ b/docs/en/advanced.md @@ -215,3 +215,122 @@ To allow Dispatcharr to connect to clients when secured behind Pangolin SSO or a * If you'd like to set up GeoBlock for any/all resources, refer to Pangolin's [official documentation](https://docs.pangolin.net/self-host/advanced/enable-geoblocking) for guidance * Test your new setup by navigating to Dispatcharr in an incognito or private window. You should now be met with your Pangolin login dashboard when accessing the WebUI when you're not authenticated, however your clients will still be able to connect to allow streaming + +--- + +## Connection Security + +TLS encrypts connections between Dispatcharr and external Redis/PostgreSQL services in [modular deployments](/Dispatcharr-Docs/installation/#modular-deployment). This prevents credentials and data from being sent in plaintext over the network. + +!!! note + Connection security is only available in modular deployment mode. AIO mode uses internal services that do not require encryption. + +### Overview + +Three levels of connection security are supported: + +| Level | What it does | When to use | +| ----- | ------------ | ----------- | +| **TLS** | Encrypts traffic between Dispatcharr and the database | Connections cross a network boundary | +| **TLS + Server Verification** | Encrypts traffic and verifies the server's identity using a CA certificate | Protecting against man-in-the-middle attacks | +| **Mutual TLS (mTLS)** | Both sides verify each other with certificates | The database server requires client authentication | + +Each level builds on the previous one. You can enable encryption without verification, or verification without mutual TLS. + +### Certificate Volume Mount + +Server verification and mutual TLS require certificate files to be accessible inside the container. If you are only encrypting the connection without verification, no certificate files are needed. + +Mount a directory containing your certificates as a read-only volume: + +```yaml +volumes: + - ./data:/data + - ./certs:/certs:ro # TLS certificates +``` + +Mount the same volume on both the `web` and `celery` services. + +### Redis TLS + +| Variable | Required | Description | +| -------- | :------: | ----------- | +| `REDIS_SSL` | Yes | Set to `true` to enable TLS | +| `REDIS_SSL_VERIFY` | No | Verify the server's identity (default: `true`). Set to `false` for self-signed certs without a CA | +| `REDIS_SSL_CA_CERT` | No | Path to the CA certificate used to verify the server | +| `REDIS_SSL_CERT` | No | Path to the client certificate (only if the server requires client authentication) | +| `REDIS_SSL_KEY` | No | Path to the client private key (only if the server requires client authentication) | + +??? example "Redis TLS — encrypted, no verification" + ```yaml + environment: + - REDIS_SSL=true + - REDIS_SSL_VERIFY=false + ``` + +??? example "Redis TLS — encrypted with server verification" + ```yaml + environment: + - REDIS_SSL=true + - REDIS_SSL_VERIFY=true + - REDIS_SSL_CA_CERT=/certs/redis/ca.crt + ``` + +??? example "Redis mTLS — mutual authentication" + ```yaml + environment: + - REDIS_SSL=true + - REDIS_SSL_VERIFY=true + - REDIS_SSL_CA_CERT=/certs/redis/ca.crt + - REDIS_SSL_CERT=/certs/redis/client.crt + - REDIS_SSL_KEY=/certs/redis/client.key + ``` + +### PostgreSQL TLS + +| Variable | Required | Description | +| -------- | :------: | ----------- | +| `POSTGRES_SSL` | Yes | Set to `true` to enable TLS | +| `POSTGRES_SSL_MODE` | No | How strictly to verify the server (default: `verify-full`). Options: `verify-full`, `verify-ca`, `require` | +| `POSTGRES_SSL_CA_CERT` | No | Path to the CA certificate used to verify the server | +| `POSTGRES_SSL_CERT` | No | Path to the client certificate (only if the server requires client authentication) | +| `POSTGRES_SSL_KEY` | No | Path to the client private key (only if the server requires client authentication) | + +**Verification modes:** + +* `verify-full` — verifies the server certificate and checks that the hostname matches (most secure, default) +* `verify-ca` — verifies the server certificate but does not check the hostname +* `require` — encrypts the connection but does not verify the server's identity + +??? example "PostgreSQL TLS — encrypted with full verification" + ```yaml + environment: + - POSTGRES_SSL=true + - POSTGRES_SSL_MODE=verify-full + - POSTGRES_SSL_CA_CERT=/certs/postgres/ca.crt + ``` + +??? example "PostgreSQL TLS — encrypted, no verification" + ```yaml + environment: + - POSTGRES_SSL=true + - POSTGRES_SSL_MODE=require + ``` + +??? example "PostgreSQL mTLS — mutual authentication" + ```yaml + environment: + - POSTGRES_SSL=true + - POSTGRES_SSL_MODE=verify-full + - POSTGRES_SSL_CA_CERT=/certs/postgres/ca.crt + - POSTGRES_SSL_CERT=/certs/postgres/client.crt + - POSTGRES_SSL_KEY=/certs/postgres/client.key + ``` + +### Important Notes + +* TLS environment variables must match across the `web` and `celery` services +* Certificate paths refer to paths inside the container, not on the host +* Dispatcharr validates certificate file paths at startup and will fail with a clear error message if a file is not found +* If you override `REDIS_URL` or `CELERY_BROKER_URL` with a custom value, the URL scheme (`redis://` vs `rediss://`) must match the `REDIS_SSL` setting. Most users do not need to set these — Dispatcharr builds the URL automatically +* The Connection Security panel in [System Settings](/Dispatcharr-Docs/system/#connection-security) displays the current TLS status for each service diff --git a/docs/en/installation.md b/docs/en/installation.md index 17268a8..6678066 100644 --- a/docs/en/installation.md +++ b/docs/en/installation.md @@ -181,6 +181,35 @@ Install Docker using the official instructions, such as those for [Ubuntu](https --- +--- + +## Modular Deployment + +By default, Dispatcharr runs in all-in-one (AIO) mode with Redis and PostgreSQL bundled inside a single container. Modular deployment separates these into individual containers, giving you control over database versions, resource allocation, and connection security. + +!!! note + Modular deployment is optional. AIO mode works for most users. Consider modular deployment if you need TLS-encrypted database connections, want to use existing external Redis or PostgreSQL instances, or require independent scaling of services. + +### Modular Docker Compose + +```yaml +--8<-- "https://raw.githubusercontent.com/Dispatcharr/Dispatcharr/refs/heads/main/docker/docker-compose.yml" +``` + +### Key Differences from AIO + +* `DISPATCHARR_ENV=modular` replaces `DISPATCHARR_ENV=aio` +* PostgreSQL and Redis run as separate containers with their own health checks +* The Celery worker runs in a dedicated container with its own entrypoint +* Environment variables for PostgreSQL and Redis must match across the web and celery services +* TLS encryption for database connections is only available in modular mode + +### TLS Configuration + +Modular deployments support TLS encryption for connections between Dispatcharr and external Redis/PostgreSQL services. See [Connection Security](/Dispatcharr-Docs/advanced/#connection-security) in the Advanced section for configuration details. + +--- + ## Accessing Dispatcharr Open your web browser and navigate to: diff --git a/docs/en/system.md b/docs/en/system.md index 6cc6b6b..5eefaae 100644 --- a/docs/en/system.md +++ b/docs/en/system.md @@ -78,6 +78,16 @@ Configure how many system events (channel start/stop, buffering, etc.) to keep i * Maximum System Events - Number of events to retain (minimum: 10, maximum: 1000) +### Connection Security +Displays the current TLS encryption status for Redis and PostgreSQL connections. This section is only visible in [modular deployment mode](/Dispatcharr-Docs/installation/#modular-deployment). + +* **Encryption** - Whether TLS is enabled for the connection +* **Server Verification** (Redis) / **Verification Mode** (PostgreSQL) - Whether the server's identity is verified using a CA certificate +* **Mutual TLS** - Whether Dispatcharr authenticates to the server using a client certificate + +!!! note + Connection Security is read-only. TLS is configured via environment variables in the docker compose file. See [Connection Security](/Dispatcharr-Docs/advanced/#connection-security) in the Advanced section for configuration details. + ### User-Agents In the context of IPTV, a user agent is a string of text that identifies the client application (e.g., a player like Kodi or VLC) to the IPTV server. It's included in the HTTP headers of requests sent by the client to the server, informing the server about the type of device and software used to access the IPTV stream. Default Dispatcharr User-Agents are available for VLC, Chrome, and TiviMate.