diff --git a/docs/_meta.json b/docs/_meta.json index 9ed6ab313..fd524d39e 100644 --- a/docs/_meta.json +++ b/docs/_meta.json @@ -69,11 +69,6 @@ "label": "Configuration Reference", "name": "/reference/config" }, - { - "type": "file", - "label": "Environment Variables", - "name": "/reference/environment-variables" - }, { "type": "dir", "label": "Admin Command Reference", diff --git a/docs/_nav.json b/docs/_nav.json index e75ed4042..fba04bc16 100644 --- a/docs/_nav.json +++ b/docs/_nav.json @@ -16,10 +16,6 @@ "text": "Configuration Reference", "link": "/reference/config" }, - { - "text": "Environment Variables Reference", - "link": "/reference/environment-variables" - }, { "text": "Admin Command Reference", "link": "/reference/admin/" diff --git a/docs/configuration.mdx b/docs/configuration.mdx index bf6f01f3b..6c66a0af5 100644 --- a/docs/configuration.mdx +++ b/docs/configuration.mdx @@ -18,7 +18,7 @@ Alternatively, you can use the environment variable `CONTINUWUITY_CONFIG` to spe All of the config file settings can also be specified by using environment variables. This makes it ideal for containerised deployments and infrastructure-as-code scenarios. -The environment variable names should be all caps and prefixed with `CONTINUWUITY_`. They are mapped to the configuration file with the syntaxes as demonstrated below: +The environment variable names is represented in all caps and prefixed with `CONTINUWUITY_`. They are mapped to the configuration file with the syntaxes as demonstrated below: ```bash # Top-level configs (those inside the [global] section) are simply capitalized @@ -39,8 +39,6 @@ CONTINUWUITY_ANTISPAM__DRAUPNIR__BASE_URL="https://draupnir.example.com" CONTINUWUITY_WELL_KNOWN={ client=https://example.com,server=example.com:443 } ``` -Please refer to the [Env Var Reference page](./reference/environment-variables.mdx) for a more detailed list of environment variables. - ### Alternative prefixes For backwards compatibility, Continuwuity also supports the following environment variable prefixes, in order of descending priority: diff --git a/docs/reference/_meta.json b/docs/reference/_meta.json index 06f442677..6d75c345c 100644 --- a/docs/reference/_meta.json +++ b/docs/reference/_meta.json @@ -4,11 +4,6 @@ "name": "config", "label": "Configuration" }, - { - "type": "file", - "name": "environment-variables", - "label": "Environment Variables" - }, { "type": "file", "name": "admin", diff --git a/docs/reference/environment-variables.mdx b/docs/reference/environment-variables.mdx deleted file mode 100644 index 8f20829a3..000000000 --- a/docs/reference/environment-variables.mdx +++ /dev/null @@ -1,245 +0,0 @@ -# Environment Variables - -This is a convenience reference and may not be exhaustive. The -[Configuration Reference](./config.mdx) is the primary source for all -configuration options. - -To see how these variables can be used, head over to the [Configuration](../configuration#environment-variables) documentation - -## Essential Variables - -These are the minimum variables needed for a working deployment: - -| Variable | Description | Default | -| ---------------------------- | ---------------------------------- | ---------------------- | -| `CONTINUWUITY_SERVER_NAME` | Your Matrix server's domain name | Required | -| `CONTINUWUITY_DATABASE_PATH` | Path to RocksDB database directory | `/var/lib/conduwuit` | -| `CONTINUWUITY_ADDRESS` | IP address to bind to | `["127.0.0.1", "::1"]` | -| `CONTINUWUITY_PORT` | Port to listen on | `8008` | - -## Network Configuration - -| Variable | Description | Default | -| -------------------------------- | ----------------------------------------------- | ---------------------- | -| `CONTINUWUITY_ADDRESS` | Bind address (use `0.0.0.0` for all interfaces) | `["127.0.0.1", "::1"]` | -| `CONTINUWUITY_PORT` | HTTP port | `8008` | -| `CONTINUWUITY_UNIX_SOCKET_PATH` | UNIX socket path (alternative to TCP) | - | -| `CONTINUWUITY_UNIX_SOCKET_PERMS` | Socket permissions (octal) | `660` | - -## Database Configuration - -| Variable | Description | Default | -| ------------------------------------------ | --------------------------- | -------------------- | -| `CONTINUWUITY_DATABASE_PATH` | RocksDB data directory | `/var/lib/conduwuit` | -| `CONTINUWUITY_DATABASE_BACKUP_PATH` | Backup directory | - | -| `CONTINUWUITY_DATABASE_BACKUPS_TO_KEEP` | Number of backups to retain | `1` | -| `CONTINUWUITY_DB_CACHE_CAPACITY_MB` | Database read cache (MB) | - | -| `CONTINUWUITY_DB_WRITE_BUFFER_CAPACITY_MB` | Write cache (MB) | - | - -## Cache Configuration - -| Variable | Description | -| ---------------------------------------- | ------------------------ | -| `CONTINUWUITY_CACHE_CAPACITY_MODIFIER` | LRU cache multiplier | -| `CONTINUWUITY_PDU_CACHE_CAPACITY` | PDU cache entries | -| `CONTINUWUITY_AUTH_CHAIN_CACHE_CAPACITY` | Auth chain cache entries | - -## DNS Configuration - -Configure DNS resolution behaviour for federation and external requests. - -| Variable | Description | Default | -| ------------------------------------ | ---------------------------- | -------- | -| `CONTINUWUITY_DNS_CACHE_ENTRIES` | Max DNS cache entries | `32768` | -| `CONTINUWUITY_DNS_MIN_TTL` | Minimum cache TTL (seconds) | `10800` | -| `CONTINUWUITY_DNS_MIN_TTL_NXDOMAIN` | NXDOMAIN cache TTL (seconds) | `259200` | -| `CONTINUWUITY_DNS_ATTEMPTS` | Retry attempts | - | -| `CONTINUWUITY_DNS_TIMEOUT` | Query timeout (seconds) | - | -| `CONTINUWUITY_DNS_TCP_FALLBACK` | Allow TCP fallback | - | -| `CONTINUWUITY_QUERY_ALL_NAMESERVERS` | Query all nameservers | - | -| `CONTINUWUITY_QUERY_OVER_TCP_ONLY` | TCP-only queries | - | - -## Request Configuration - -| Variable | Description | -| ------------------------------------ | ----------------------------- | -| `CONTINUWUITY_MAX_REQUEST_SIZE` | Max HTTP request size (bytes) | -| `CONTINUWUITY_REQUEST_CONN_TIMEOUT` | Connection timeout (seconds) | -| `CONTINUWUITY_REQUEST_TIMEOUT` | Overall request timeout | -| `CONTINUWUITY_REQUEST_TOTAL_TIMEOUT` | Total timeout | -| `CONTINUWUITY_REQUEST_IDLE_TIMEOUT` | Idle timeout | -| `CONTINUWUITY_REQUEST_IDLE_PER_HOST` | Idle connections per host | - -## Federation Configuration - -Control how your server federates with other Matrix servers. - -| Variable | Description | Default | -| ---------------------------------------------- | ----------------------------- | ------- | -| `CONTINUWUITY_ALLOW_FEDERATION` | Enable federation | `true` | -| `CONTINUWUITY_FEDERATION_LOOPBACK` | Allow loopback federation | - | -| `CONTINUWUITY_FEDERATION_CONN_TIMEOUT` | Connection timeout | - | -| `CONTINUWUITY_FEDERATION_TIMEOUT` | Request timeout | - | -| `CONTINUWUITY_FEDERATION_IDLE_TIMEOUT` | Idle timeout | - | -| `CONTINUWUITY_FEDERATION_IDLE_PER_HOST` | Idle connections per host | - | -| `CONTINUWUITY_TRUSTED_SERVERS` | JSON array of trusted servers | - | -| `CONTINUWUITY_QUERY_TRUSTED_KEY_SERVERS_FIRST` | Query trusted first | - | -| `CONTINUWUITY_ONLY_QUERY_TRUSTED_KEY_SERVERS` | Only query trusted | - | - -**Example:** - -```bash -# Trust matrix.org for key verification -CONTINUWUITY_TRUSTED_SERVERS='["matrix.org"]' -``` - -## Registration & User Configuration - -Control user registration and account creation behaviour. - -| Variable | Description | Default | -| ------------------------------------------ | --------------------- | ------- | -| `CONTINUWUITY_ALLOW_REGISTRATION` | Enable registration | `true` | -| `CONTINUWUITY_REGISTRATION_TOKEN` | Token requirement | - | -| `CONTINUWUITY_SUSPEND_ON_REGISTER` | Suspend new accounts | - | -| `CONTINUWUITY_NEW_USER_DISPLAYNAME_SUFFIX` | Display name suffix | 🏳️‍⚧️ | -| `CONTINUWUITY_RECAPTCHA_SITE_KEY` | reCAPTCHA site key | - | -| `CONTINUWUITY_RECAPTCHA_PRIVATE_SITE_KEY` | reCAPTCHA private key | - | - -**Example:** - -```bash -# Disable open registration -CONTINUWUITY_ALLOW_REGISTRATION="false" - -# Require a registration token -CONTINUWUITY_REGISTRATION_TOKEN="your_secret_token_here" -``` - -## Feature Configuration - -| Variable | Description | Default | -| ---------------------------------------------------------- | -------------------------- | ------- | -| `CONTINUWUITY_ALLOW_ENCRYPTION` | Enable E2EE | `true` | -| `CONTINUWUITY_ALLOW_ROOM_CREATION` | Enable room creation | - | -| `CONTINUWUITY_ALLOW_UNSTABLE_ROOM_VERSIONS` | Allow unstable versions | - | -| `CONTINUWUITY_DEFAULT_ROOM_VERSION` | Default room version | `v11` | -| `CONTINUWUITY_REQUIRE_AUTH_FOR_PROFILE_REQUESTS` | Auth for profiles | - | -| `CONTINUWUITY_ALLOW_PUBLIC_ROOM_DIRECTORY_OVER_FEDERATION` | Federate directory | - | -| `CONTINUWUITY_ALLOW_PUBLIC_ROOM_DIRECTORY_WITHOUT_AUTH` | Unauth directory | - | -| `CONTINUWUITY_ALLOW_DEVICE_NAME_FEDERATION` | Device names in federation | - | - -## TLS Configuration - -Built-in TLS support is primarily for testing. **For production deployments, -especially when federating on the internet, use a reverse proxy** (Traefik, -Caddy, nginx) to handle TLS termination. - -| Variable | Description | -| --------------------------------- | ------------------------- | -| `CONTINUWUITY_TLS__CERTS` | TLS certificate file path | -| `CONTINUWUITY_TLS__KEY` | TLS private key path | -| `CONTINUWUITY_TLS__DUAL_PROTOCOL` | Support TLS 1.2 + 1.3 | - -**Example (testing only):** - -```bash -CONTINUWUITY_TLS__CERTS="/etc/letsencrypt/live/matrix.example.com/fullchain.pem" -CONTINUWUITY_TLS__KEY="/etc/letsencrypt/live/matrix.example.com/privkey.pem" -``` - -## Logging Configuration - -Control log output format and verbosity. - -| Variable | Description | Default | -| ------------------------------ | ------------------ | ------- | -| `CONTINUWUITY_LOG` | Log filter level | - | -| `CONTINUWUITY_LOG_COLORS` | ANSI colours | `true` | -| `CONTINUWUITY_LOG_SPAN_EVENTS` | Log span events | `none` | -| `CONTINUWUITY_LOG_THREAD_IDS` | Include thread IDs | - | - -**Examples:** - -```bash -# Set log level to info -CONTINUWUITY_LOG="info" - -# Enable debug logging for specific modules -CONTINUWUITY_LOG="warn,continuwuity::api=debug" - -# Disable colours for log aggregation -CONTINUWUITY_LOG_COLORS="false" -``` - -## Observability Configuration - -| Variable | Description | -| ---------------------------------------- | --------------------- | -| `CONTINUWUITY_ALLOW_OTLP` | Enable OpenTelemetry | -| `CONTINUWUITY_OTLP_FILTER` | OTLP filter level | -| `CONTINUWUITY_OTLP_PROTOCOL` | Protocol (http/grpc) | -| `CONTINUWUITY_TRACING_FLAME` | Enable flame graphs | -| `CONTINUWUITY_TRACING_FLAME_FILTER` | Flame graph filter | -| `CONTINUWUITY_TRACING_FLAME_OUTPUT_PATH` | Output directory | -| `CONTINUWUITY_SENTRY` | Enable Sentry | -| `CONTINUWUITY_SENTRY_ENDPOINT` | Sentry DSN | -| `CONTINUWUITY_SENTRY_SEND_SERVER_NAME` | Include server name | -| `CONTINUWUITY_SENTRY_TRACES_SAMPLE_RATE` | Sample rate (0.0-1.0) | - -## Admin Configuration - -Configure admin users and automated command execution. - -| Variable | Description | Default | -| ------------------------------------------ | -------------------------------- | ----------------- | -| `CONTINUWUITY_ADMINS_LIST` | JSON array of admin user IDs | - | -| `CONTINUWUITY_ADMINS_FROM_ROOM` | Derive admins from room | - | -| `CONTINUWUITY_ADMIN_ESCAPE_COMMANDS` | Allow `\` prefix in public rooms | - | -| `CONTINUWUITY_ADMIN_CONSOLE_AUTOMATIC` | Auto-activate console | - | -| `CONTINUWUITY_ADMIN_EXECUTE` | JSON array of startup commands | - | -| `CONTINUWUITY_ADMIN_EXECUTE_ERRORS_IGNORE` | Ignore command errors | - | -| `CONTINUWUITY_ADMIN_SIGNAL_EXECUTE` | Commands on SIGUSR2 | - | -| `CONTINUWUITY_ADMIN_ROOM_TAG` | Admin room tag | `m.server_notice` | - -**Examples:** - -```bash -# Create admin user on startup -CONTINUWUITY_ADMIN_EXECUTE='["users create-user admin", "users make-user-admin admin"]' - -# Specify admin users directly -CONTINUWUITY_ADMINS_LIST='["@alice:example.com", "@bob:example.com"]' -``` - -## Media & URL Preview Configuration - -| Variable | Description | -| ---------------------------------------------------- | ------------------ | -| `CONTINUWUITY_URL_PREVIEW_BOUND_INTERFACE` | Bind interface | -| `CONTINUWUITY_URL_PREVIEW_DOMAIN_CONTAINS_ALLOWLIST` | Domain allowlist | -| `CONTINUWUITY_URL_PREVIEW_DOMAIN_EXPLICIT_ALLOWLIST` | Explicit allowlist | -| `CONTINUWUITY_URL_PREVIEW_DOMAIN_EXPLICIT_DENYLIST` | Explicit denylist | -| `CONTINUWUITY_URL_PREVIEW_MAX_SPIDER_SIZE` | Max fetch size | -| `CONTINUWUITY_URL_PREVIEW_TIMEOUT` | Fetch timeout | -| `CONTINUWUITY_IP_RANGE_DENYLIST` | IP range denylist | - -## Tokio Runtime Configuration - -These can be set as environment variables or CLI arguments: - -| Variable | Description | -| ----------------------------------------- | -------------------------- | -| `TOKIO_WORKER_THREADS` | Worker thread count | -| `TOKIO_GLOBAL_QUEUE_INTERVAL` | Global queue interval | -| `TOKIO_EVENT_INTERVAL` | Event interval | -| `TOKIO_MAX_IO_EVENTS_PER_TICK` | Max I/O events per tick | -| `CONTINUWUITY_RUNTIME_HISTOGRAM_INTERVAL` | Histogram bucket size (μs) | -| `CONTINUWUITY_RUNTIME_HISTOGRAM_BUCKETS` | Bucket count | -| `CONTINUWUITY_RUNTIME_WORKER_AFFINITY` | Enable worker affinity | - -## See Also - -- [Configuration Reference](./config.mdx) - Complete TOML configuration - documentation -- [Admin Commands](./admin/) - Admin command reference