continuwuity/docs/configuration.mdx

# Configuration

This chapter describes various ways to configure Continuwuity.

## Configuration file

Continuwuity uses a config file for the majority of the settings. This is the recommended way to configure Continuwuity. Please refer to the [example config file](./reference/config.mdx) for all of those settings.

The config file to use can be specified on the commandline when running Continuwuity by specifying the `-c`/ `--config` flag:

```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 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:

```bash
# Top-level configs (those inside the [global] section) are simply capitalized
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 JSON object to define the entire section
# This maps to the [global.well_known] section
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:

- `CONDUWUIT_*` (compatibility)
- `CONDUIT_*` (legacy)

So, for 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 prioritized, 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.

---

## Execute startup commands

Continuwuity supports running admin commands on startup using the commandline argument `--execute`. The syntax of this is a standard admin command without the `!admin` prefix. For example, to create a new user:

```
./conduwuit --execute "users create_user june"
```

An example output of a success is:

```
INFO conduwuit_service::admin::startup: Startup command #0 completed:
Created user with user_id: @june:girlboss.ceo and password: `<redacted>`
```

This commandline argument can be paired with the `--option` flag.

Alternatively, you can configure `CONTINUWUITY_ADMIN_EXECUTE` or the config file value `admin_execute` with a list of commands.