forked from continuwuation/continuwuity
stratself
ed76f50e71
* CONTINUWUITY_WELL_KNOWN requires a "Struct", not a JSON array * Fix all instances of Intl English to English English * Typo/grammar nits fixings
91 lines
3.8 KiB
Text
91 lines
3.8 KiB
Text
# Configuration
|
|
|
|
This chapter describes various ways to configure Continuwuity.
|
|
|
|
## Configuration file
|
|
|
|
Continuwuity uses a TOML config file for all of its settings. This is the recommended way to configure Continuwuity. Please refer to the [example config file](./reference/config.mdx) for all of these settings.
|
|
|
|
You can specify the config file to be used by Continuwuity with the command-line flag `-c` or `--config`:
|
|
|
|
```bash
|
|
./conduwuit -c /path/to/continuwuity.toml
|
|
```
|
|
|
|
Alternatively, you can use the environment variable `CONTINUWUITY_CONFIG` to specify the config file to be used; see [the section on environment variables](#environment-variables) for more information.
|
|
|
|
## Environment variables
|
|
|
|
All of the options in the config file can also be specified by using environment variables. This is ideal for containerised deployments and infrastructure-as-code scenarios.
|
|
|
|
The environment variable names are represented in all caps and prefixed with `CONTINUWUITY_`. They are mapped to config options in the ways demonstrated below:
|
|
|
|
```bash
|
|
# Top-level options (those inside the [global] section) are simply capitalised
|
|
CONTINUWUITY_SERVER_NAME="matrix.example.com"
|
|
CONTINUWUITY_PORT="8008"
|
|
CONTINUWUITY_DATABASE_PATH="/var/lib/continuwuity"
|
|
|
|
# Nested config sections use double underscores `__`
|
|
|
|
# This maps to the `server` field of the [global.well_known] section in TOML
|
|
CONTINUWUITY_WELL_KNOWN__SERVER="example.com:443"
|
|
|
|
# This maps to the `base_url` field of the `[global.antispam.draupnir]` section in TOML
|
|
CONTINUWUITY_ANTISPAM__DRAUPNIR__BASE_URL="https://draupnir.example.com"
|
|
|
|
# Alternatively, you can pass a (quoted) struct to define an entire section
|
|
# This maps to the [global.well_known] section
|
|
CONTINUWUITY_WELL_KNOWN="{ client=https://example.com,server=example.com:443 }"
|
|
```
|
|
|
|
### Alternative prefixes
|
|
|
|
For backwards compatibility, Continuwuity also supports the following environment variable prefixes, in order of descending priority:
|
|
|
|
- `CONDUWUIT_*` (compatibility)
|
|
- `CONDUIT_*` (legacy)
|
|
|
|
As an example, the environment variable `CONTINUWUITY_CONFIG` can also be expressed as `CONDUWUIT_CONFIG` or `CONDUIT_CONFIG`.
|
|
|
|
## Option command-line flag
|
|
|
|
Continuwuity also supports setting individual config options in TOML format from the `-O` / `--option` flag. For example, you can set your server name via `-O server_name=\"example.com\"`.
|
|
|
|
Note that the config is parsed as TOML, and shells like `bash` will remove quotes. Therefore, if the config option is a string, quote escapes must be properly handled. If the config option is a number or a boolean, this does not apply.
|
|
|
|
- `--option allow_registration=true` works ✅
|
|
- `-O max_request_size=99999999` works ✅
|
|
- `-O server_name=example.com` does not work ❌
|
|
- `--option log=\"debug\"` works ✅
|
|
- `--option server_name='"example.com'"` works ✅
|
|
|
|
## Order of priority
|
|
|
|
The above configuration methods are prioritised, in descending order, as below:
|
|
|
|
- Command-line `-o`/`--option` flags
|
|
- Environment variables
|
|
- `CONTINUWUITY_*` variables
|
|
- `CONDUWUIT_*` variables
|
|
- `CONDUIT_*` variables
|
|
- Config file
|
|
|
|
Therefore, you can use environment variables or the options flags to override values in the config file.
|
|
|
|
---
|
|
|
|
## Executing startup commands
|
|
|
|
Continuwuity supports running admin commands on startup using the command-line flag `--execute`. This is treated as a standard admin command, without the need for the `!admin` prefix. For example, to create a new user:
|
|
|
|
```bash
|
|
# Equivalent to `!admin users create_user june`
|
|
./conduwuit --execute "users create_user june"
|
|
INFO conduwuit_service::admin::startup: Startup command #0 completed:
|
|
Created user with user_id: @june:girlboss.ceo and password: `<redacted>`
|
|
```
|
|
|
|
Alternatively, you can configure `CONTINUWUITY_ADMIN_EXECUTE` or the config file value `admin_execute` with a list of commands.
|
|
|
|
This command-line argument can be paired with the `--option` flag.
|