diff --git a/docs/_meta.json b/docs/_meta.json index fd524d39..9ed6ab31 100644 --- a/docs/_meta.json +++ b/docs/_meta.json @@ -69,6 +69,11 @@ "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/deploying/docker-compose.for-traefik.yml b/docs/deploying/docker-compose.for-traefik.yml index 632dd5de..369d6eb6 100644 --- a/docs/deploying/docker-compose.for-traefik.yml +++ b/docs/deploying/docker-compose.for-traefik.yml @@ -8,7 +8,6 @@ services: restart: unless-stopped volumes: - db:/var/lib/continuwuity - - /etc/resolv.conf:/etc/resolv.conf:ro # Use the host's DNS resolver rather than Docker's. #- ./continuwuity.toml:/etc/continuwuity.toml networks: - proxy diff --git a/docs/deploying/docker.mdx b/docs/deploying/docker.mdx index f778a585..c3260778 100644 --- a/docs/deploying/docker.mdx +++ b/docs/deploying/docker.mdx @@ -2,28 +2,26 @@ ## Docker -To run Continuwuity with Docker, you can either build the image yourself or pull it -from a registry. +To run Continuwuity with Docker, you can either build the image yourself or pull +it from a registry. ### Use a registry -OCI images for Continuwuity are available in the registries listed below. +Available OCI images: -| Registry | Image | Notes | -| --------------- | --------------------------------------------------------------- | -----------------------| -| Forgejo Registry| [forgejo.ellis.link/continuwuation/continuwuity:latest](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/latest) | Latest tagged image. | -| Forgejo Registry| [forgejo.ellis.link/continuwuation/continuwuity:main](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/main) | Main branch image. | -| Forgejo Registry| [forgejo.ellis.link/continuwuation/continuwuity:latest-maxperf](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/latest-maxperf) | [Performance optimised version.](./generic.mdx#performance-optimised-builds) | -| Forgejo Registry| [forgejo.ellis.link/continuwuation/continuwuity:main-maxperf](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/main-maxperf) | [Performance optimised version.](./generic.mdx#performance-optimised-builds) | +| Registry | Image | Notes | +| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| Forgejo Registry | [forgejo.ellis.link/continuwuation/continuwuity:latest](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/latest) | Latest tagged image. | +| Forgejo Registry | [forgejo.ellis.link/continuwuation/continuwuity:main](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/main) | Main branch image. | +| Forgejo Registry | [forgejo.ellis.link/continuwuation/continuwuity:latest-maxperf](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/latest-maxperf) | [Performance optimised version.](./generic.mdx#performance-optimised-builds) | +| Forgejo Registry | [forgejo.ellis.link/continuwuation/continuwuity:main-maxperf](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/main-maxperf) | [Performance optimised version.](./generic.mdx#performance-optimised-builds) | -Use +**Example:** ```bash -docker image pull $LINK +docker image pull forgejo.ellis.link/continuwuation/continuwuity:main-maxperf ``` -to pull it to your machine. - #### Mirrors Images are mirrored to multiple locations automatically, on a schedule: @@ -33,39 +31,146 @@ Images are mirrored to multiple locations automatically, on a schedule: - `registry.gitlab.com/continuwuity/continuwuity` - `git.nexy7574.co.uk/mirrored/continuwuity` (releases only, no `main`) -### Run +### Quick Run -When you have the image, you can simply run it with +Get a working Continuwuity server with an admin user in four steps: + +#### Prerequisites + +Continuwuity requires HTTPS for Matrix federation. You'll need: + +- A domain name pointing to your server +- A reverse proxy with SSL/TLS certificates (Traefik, Caddy, nginx, etc.) + +See [Docker Compose](#docker-compose) for complete examples. + +#### Environment Variables + +- `CONTINUWUITY_SERVER_NAME` - Your Matrix server's domain name +- `CONTINUWUITY_DATABASE_PATH` - Where to store your database (must match the + volume mount) +- `CONTINUWUITY_ADDRESS` - Bind address (use `0.0.0.0` to listen on all + interfaces) +- `CONTINUWUITY_ALLOW_REGISTRATION` - Set to `false` to disable registration, or + use with `CONTINUWUITY_REGISTRATION_TOKEN` to require a token (see + [reference](../reference/environment-variables.mdx#registration--user-configuration) + for details) + +See the +[Environment Variables Reference](../reference/environment-variables.mdx) for +more configuration options. + +#### 1. Pull the image ```bash -docker run -d -p 8448:6167 \ - -v db:/var/lib/continuwuity/ \ - -e CONTINUWUITY_SERVER_NAME="your.server.name" \ - -e CONTINUWUITY_ALLOW_REGISTRATION=false \ - --name continuwuity $LINK +docker pull forgejo.ellis.link/continuwuation/continuwuity:latest ``` -or you can use [Docker Compose](#docker-compose). +#### 2. Start the server with initial admin user -The `-d` flag lets the container run in detached mode. You may supply an -optional `continuwuity.toml` config file, the example config can be found -[here](../reference/config.mdx). You can pass in different env vars to -change config values on the fly. You can even configure Continuwuity completely by -using env vars. For an overview of possible values, please take a look at the -`docker-compose.yml` file. +```bash +docker run -d \ + -p 6167:6167 \ + -v continuwuity_db:/var/lib/continuwuity \ + -e CONTINUWUITY_SERVER_NAME="matrix.example.com" \ + -e CONTINUWUITY_DATABASE_PATH="/var/lib/continuwuity" \ + -e CONTINUWUITY_ADDRESS="0.0.0.0" \ + -e CONTINUWUITY_ALLOW_REGISTRATION="false" \ + --name continuwuity \ + forgejo.ellis.link/continuwuation/continuwuity:latest \ + --execute "users create-user admin" +``` -If you just want to test Continuwuity for a short time, you can use the `--rm` -flag, which cleans up everything related to your container after you stop -it. +Replace `matrix.example.com` with your actual server name and `admin` with +your preferred username. + +#### 3. Get your admin password + +```bash +docker logs continuwuity 2>&1 | grep "Created user" +``` + +You'll see output like: + +``` +Created user with user_id: @admin:matrix.example.com and password: `[auto-generated-password]` +``` + +#### 4. Configure your reverse proxy + +Configure your reverse proxy to forward HTTPS traffic to Continuwuity. See +[Docker Compose](#docker-compose) for examples. + +Once configured, log in with any Matrix client using `@admin:matrix.example.com` +and the generated password. You'll automatically be invited to the admin room +where you can manage your server. ### Docker Compose -If the `docker run` command is not suitable for you or your setup, you can also use one -of the provided `docker-compose` files. +Docker Compose is the recommended deployment method. These examples include +reverse proxy configurations for Matrix federation. -Depending on your proxy setup, you can use one of the following files: +#### Matrix Federation Requirements -### For existing Traefik setup +For Matrix federation to work, you need to serve `.well-known/matrix/client` and +`.well-known/matrix/server` endpoints. You can achieve this either by: + +1. **Using a well-known service** - The compose files below include an nginx + container to serve these files +2. **Using Continuwuity's built-in delegation** (easier for Traefik) - Configure + delegation files in your config, then proxy `/.well-known/matrix/*` to + Continuwuity + +**Traefik example using built-in delegation:** + +```yaml +labels: + traefik.http.routers.continuwuity.rule: >- + (Host(`matrix.example.com`) || + (Host(`example.com`) && PathPrefix(`/.well-known/matrix`))) +``` + +This routes your Matrix domain and well-known paths to Continuwuity. + +#### Creating Your First Admin User + +Add the `--execute` command to create an admin user on first startup. In your +compose file, add under the `continuwuity` service: + +```yaml +services: + continuwuity: + image: forgejo.ellis.link/continuwuation/continuwuity:latest + command: --execute "users create-user admin" + # ... rest of configuration +``` + +Then retrieve the auto-generated password: + +```bash +docker compose logs continuwuity | grep "Created user" +``` + +#### Choose Your Reverse Proxy + +Select the compose file that matches your setup: + +:::note DNS Performance +Docker's default DNS resolver can cause performance issues with Matrix +federation. If you experience slow federation or DNS timeouts, you may need to +use your host's DNS resolver instead. Add this volume mount to the +`continuwuity` service: + +```yaml +volumes: + - /etc/resolv.conf:/etc/resolv.conf:ro +``` + +See [Troubleshooting - DNS Issues](../troubleshooting.mdx#potential-dns-issues-when-using-docker) +for more details and alternative solutions. +::: + +##### For existing Traefik setup
docker-compose.for-traefik.yml @@ -76,7 +181,7 @@ Depending on your proxy setup, you can use one of the following files:
-### With Traefik included +##### With Traefik included
docker-compose.with-traefik.yml @@ -87,7 +192,7 @@ Depending on your proxy setup, you can use one of the following files:
-### With Caddy Docker Proxy +##### With Caddy Docker Proxy
docker-compose.with-caddy.yml @@ -98,9 +203,15 @@ Replace all `example.com` placeholders with your own domain. ``` +If you don't already have a network for Caddy to monitor, create one first: + +```bash +docker network create caddy +``` +
-### For other reverse proxies +##### For other reverse proxies
docker-compose.yml @@ -111,7 +222,7 @@ Replace all `example.com` placeholders with your own domain.
-### Override file +##### Override file for customisation
docker-compose.override.yml @@ -122,98 +233,24 @@ Replace all `example.com` placeholders with your own domain.
-When picking the Traefik-related compose file, rename it to -`docker-compose.yml`, and rename the override file to -`docker-compose.override.yml`. Edit the latter with the values you want for your -server. +#### Starting Your Server -When picking the `caddy-docker-proxy` compose file, it's important to first -create the `caddy` network before spinning up the containers: - -```bash -docker network create caddy -``` - -After that, you can rename it to `docker-compose.yml` and spin up the -containers! - -Additional info about deploying Continuwuity can be found [here](generic.mdx). - -### Build - -Official Continuwuity images are built using **Docker Buildx** and the Dockerfile found at [`docker/Dockerfile`][dockerfile-path]. This approach uses common Docker tooling and enables efficient multi-platform builds. - -The resulting images are widely compatible with Docker and other container runtimes like Podman or containerd. - -The images *do not contain a shell*. They contain only the Continuwuity binary, required libraries, TLS certificates, and metadata. - -
-Click to view the Dockerfile - -You can also view the Dockerfile on Forgejo. - -```dockerfile file="../../docker/Dockerfile" - -``` - -
- -To build an image locally using Docker Buildx, you can typically run a command like: - -```bash -# Build for the current platform and load into the local Docker daemon -docker buildx build --load --tag continuwuity:latest -f docker/Dockerfile . - -# Example: Build for specific platforms and push to a registry. -# docker buildx build --platform linux/amd64,linux/arm64 --tag registry.io/org/continuwuity:latest -f docker/Dockerfile . --push - -# Example: Build binary optimised for the current CPU (standard release profile) -# docker buildx build --load \ -# --tag continuwuity:latest \ -# --build-arg TARGET_CPU=native \ -# -f docker/Dockerfile . - -# Example: Build maxperf variant (release-max-perf profile with LTO) -# Optimised for runtime performance and smaller binary size, but requires longer build time -# docker buildx build --load \ -# --tag continuwuity:latest-maxperf \ -# --build-arg TARGET_CPU=native \ -# --build-arg RUST_PROFILE=release-max-perf \ -# -f docker/Dockerfile . -``` - -Refer to the Docker Buildx documentation for more advanced build options. - -[dockerfile-path]: https://forgejo.ellis.link/continuwuation/continuwuation/src/branch/main/docker/Dockerfile - -### Run - -If you have already built the image or want to use one from the registries, you -can start the container and everything else in the compose file in detached -mode with: +1. Choose your compose file and rename it to `docker-compose.yml` +2. If using the override file, rename it to `docker-compose.override.yml` and + edit your values +3. Start the server: ```bash docker compose up -d ``` -> **Note:** Don't forget to modify and adjust the compose file to your needs. +See the [generic deployment guide](generic.mdx) for more deployment options. -### Use Traefik as Proxy +### Building Custom Images -As a container user, you probably know about Traefik. It is an easy-to-use -reverse proxy for making containerized apps and services available through the -web. With the Traefik-related docker-compose files provided above, it is equally easy -to deploy and use Continuwuity, with a small caveat. If you have already looked at -the files, you should have seen the `well-known` service, which is the -small caveat. Traefik is simply a proxy and load balancer and cannot -serve any kind of content. For Continuwuity to federate, we need to either -expose ports `443` and `8448` or serve two endpoints: `.well-known/matrix/client` -and `.well-known/matrix/server`. - -With the service `well-known`, we use a single `nginx` container that serves -those two files. - -Alternatively, you can use Continuwuity's built-in delegation file capability. Set up the delegation files in the configuration file, and then proxy paths under `/.well-known/matrix` to continuwuity. For example, the label ``traefik.http.routers.continuwuity.rule=(Host(`matrix.ellis.link`) || (Host(`ellis.link`) && PathPrefix(`/.well-known/matrix`)))`` does this for the domain `ellis.link`. +For information on building your own Continuwuity Docker images, see the +[Building Docker Images](../development/index.mdx#building-docker-images) +section in the development documentation. ## Voice communication diff --git a/docs/development/index.mdx b/docs/development/index.mdx index 62f15e79..1a138072 100644 --- a/docs/development/index.mdx +++ b/docs/development/index.mdx @@ -2,7 +2,8 @@ Information about developing the project. If you are only interested in using it, you can safely ignore this page. If you plan on contributing, see the -[contributor's guide](./contributing.mdx) and [code style guide](./code_style.mdx). +[contributor's guide](./contributing.mdx) and +[code style guide](./code_style.mdx). ## Continuwuity project layout @@ -12,86 +13,98 @@ members are under `src/`. The workspace definition is at the top level / root `Cargo.toml`. The crate names are generally self-explanatory: + - `admin` is the admin room - `api` is the HTTP API, Matrix C-S and S-S endpoints, etc -- `core` is core Continuwuity functionality like config loading, error definitions, -global utilities, logging infrastructure, etc -- `database` is RocksDB methods, helpers, RocksDB config, and general database definitions, -utilities, or functions -- `macros` are Continuwuity Rust [macros][macros] like general helper macros, logging -and error handling macros, and [syn][syn] and [procedural macros][proc-macro] -used for admin room commands and others +- `core` is core Continuwuity functionality like config loading, error + definitions, global utilities, logging infrastructure, etc +- `database` is RocksDB methods, helpers, RocksDB config, and general database + definitions, utilities, or functions +- `macros` are Continuwuity Rust [macros][macros] like general helper macros, + logging and error handling macros, and [syn][syn] and [procedural + macros][proc-macro] used for admin room commands and others - `main` is the "primary" sub-crate. This is where the `main()` function lives, -tokio worker and async initialisation, Sentry initialisation, [clap][clap] init, -and signal handling. If you are adding new [Rust features][features], they *must* -go here. -- `router` is the webserver and request handling bits, using axum, tower, tower-http, -hyper, etc, and the [global server state][state] to access `services`. + tokio worker and async initialisation, Sentry initialisation, [clap][clap] + init, and signal handling. If you are adding new [Rust features][features], + they _must_ go here. +- `router` is the webserver and request handling bits, using axum, tower, + tower-http, hyper, etc, and the [global server state][state] to access + `services`. - `service` is the high-level database definitions and functions for data, -outbound/sending code, and other business logic such as media fetching. + outbound/sending code, and other business logic such as media fetching. -It is highly unlikely you will ever need to add a new workspace member, but -if you truly find yourself needing to, we recommend reaching out to us in -the Matrix room for discussions about it beforehand. +It is highly unlikely you will ever need to add a new workspace member, but if +you truly find yourself needing to, we recommend reaching out to us in the +Matrix room for discussions about it beforehand. The primary inspiration for this design was apart of hot reloadable development, -to support "Continuwuity as a library" where specific parts can simply be swapped out. -There is evidence Conduit wanted to go this route too as `axum` is technically an -optional feature in Conduit, and can be compiled without the binary or axum library -for handling inbound web requests; but it was never completed or worked. +to support "Continuwuity as a library" where specific parts can simply be +swapped out. There is evidence Conduit wanted to go this route too as `axum` is +technically an optional feature in Conduit, and can be compiled without the +binary or axum library for handling inbound web requests; but it was never +completed or worked. -See the Rust documentation on [Workspaces][workspaces] for general questions -and information on Cargo workspaces. +See the Rust documentation on [Workspaces][workspaces] for general questions and +information on Cargo workspaces. ## Adding compile-time [features][features] -If you'd like to add a compile-time feature, you must first define it in -the `main` workspace crate located in `src/main/Cargo.toml`. The feature must -enable a feature in the other workspace crate(s) you intend to use it in. Then -the said workspace crate(s) must define the feature there in its `Cargo.toml`. +If you'd like to add a compile-time feature, you must first define it in the +`main` workspace crate located in `src/main/Cargo.toml`. The feature must enable +a feature in the other workspace crate(s) you intend to use it in. Then the said +workspace crate(s) must define the feature there in its `Cargo.toml`. -So, if this is adding a feature to the API such as `woof`, you define the feature -in the `api` crate's `Cargo.toml` as `woof = []`. The feature definition in `main`'s -`Cargo.toml` will be `woof = ["conduwuit-api/woof"]`. +So, if this is adding a feature to the API such as `woof`, you define the +feature in the `api` crate's `Cargo.toml` as `woof = []`. The feature definition +in `main`'s `Cargo.toml` will be `woof = ["conduwuit-api/woof"]`. -The rationale for this is due to Rust / Cargo not supporting -["workspace level features"][9], we must make a choice of; either scattering -features all over the workspace crates, making it difficult for anyone to add -or remove default features; or define all the features in one central workspace -crate that propagate down/up to the other workspace crates. It is a Cargo pitfall, -and we'd like to see better developer UX in Rust's Workspaces. +The rationale for this is due to Rust / Cargo not supporting ["workspace level +features"][9], we must make a choice of; either scattering features all over the +workspace crates, making it difficult for anyone to add or remove default +features; or define all the features in one central workspace crate that +propagate down/up to the other workspace crates. It is a Cargo pitfall, and we'd +like to see better developer UX in Rust's Workspaces. -Additionally, the definition of one single place makes "feature collection" in our -Nix flake a million times easier instead of collecting and deduping them all from -searching in all the workspace crates' `Cargo.toml`s. Though we wouldn't need to -do this if Rust supported workspace-level features to begin with. +Additionally, the definition of one single place makes "feature collection" in +our Nix flake a million times easier instead of collecting and deduping them all +from searching in all the workspace crates' `Cargo.toml`s. Though we wouldn't +need to do this if Rust supported workspace-level features to begin with. ## List of forked dependencies -During Continuwuity (and prior projects) development, we have had to fork some dependencies to support our use-cases. -These forks exist for various reasons including features that upstream projects won't accept, -faster-paced development, Continuwuity-specific usecases, or lack of time to upstream changes. +During Continuwuity (and prior projects) development, we have had to fork some +dependencies to support our use-cases. These forks exist for various reasons +including features that upstream projects won't accept, faster-paced +development, Continuwuity-specific usecases, or lack of time to upstream +changes. -All forked dependencies are maintained under the [continuwuation organization on Forgejo](https://forgejo.ellis.link/continuwuation): +All forked dependencies are maintained under the +[continuwuation organization on Forgejo](https://forgejo.ellis.link/continuwuation): -- [ruwuma][continuwuation-ruwuma] - Fork of [ruma/ruma][ruma] with various performance improvements, more features and better client/server interop -- [rocksdb][continuwuation-rocksdb] - Fork of [facebook/rocksdb][rocksdb] via [`@zaidoon1`][8] with liburing build fixes and GCC debug build fixes -- [jemallocator][continuwuation-jemallocator] - Fork of [tikv/jemallocator][jemallocator] fixing musl builds, suspicious code, - and adding support for redzones in Valgrind -- [rustyline-async][continuwuation-rustyline-async] - Fork of [zyansheep/rustyline-async][rustyline-async] with tab completion callback - and `CTRL+\` signal quit event for Continuwuity console CLI -- [rust-rocksdb][continuwuation-rust-rocksdb] - Fork of [rust-rocksdb/rust-rocksdb][rust-rocksdb] fixing musl build issues, - removing unnecessary `gtest` include, and using our RocksDB and jemallocator forks -- [tracing][continuwuation-tracing] - Fork of [tokio-rs/tracing][tracing] implementing `Clone` for `EnvFilter` to - support dynamically changing tracing environments +- [ruwuma][continuwuation-ruwuma] - Fork of [ruma/ruma][ruma] with various + performance improvements, more features and better client/server interop +- [rocksdb][continuwuation-rocksdb] - Fork of [facebook/rocksdb][rocksdb] via + [`@zaidoon1`][8] with liburing build fixes and GCC debug build fixes +- [jemallocator][continuwuation-jemallocator] - Fork of + [tikv/jemallocator][jemallocator] fixing musl builds, suspicious code, and + adding support for redzones in Valgrind +- [rustyline-async][continuwuation-rustyline-async] - Fork of + [zyansheep/rustyline-async][rustyline-async] with tab completion callback and + `CTRL+\` signal quit event for Continuwuity console CLI +- [rust-rocksdb][continuwuation-rust-rocksdb] - Fork of + [rust-rocksdb/rust-rocksdb][rust-rocksdb] fixing musl build issues, removing + unnecessary `gtest` include, and using our RocksDB and jemallocator forks +- [tracing][continuwuation-tracing] - Fork of [tokio-rs/tracing][tracing] + implementing `Clone` for `EnvFilter` to support dynamically changing tracing + environments ## Debugging with `tokio-console` [`tokio-console`][7] can be a useful tool for debugging and profiling. To make a -`tokio-console`-enabled build of Continuwuity, enable the `tokio_console` feature, -disable the default `release_max_log_level` feature, and set the `--cfg -tokio_unstable` flag to enable experimental tokio APIs. A build might look like -this: +`tokio-console`-enabled build of Continuwuity, enable the `tokio_console` +feature, disable the default `release_max_log_level` feature, and set the +`--cfg tokio_unstable` flag to enable experimental tokio APIs. A build might +look like this: ```bash RUSTFLAGS="--cfg tokio_unstable" cargo +nightly build \ @@ -100,34 +113,84 @@ RUSTFLAGS="--cfg tokio_unstable" cargo +nightly build \ --features=systemd,element_hacks,gzip_compression,brotli_compression,zstd_compression,tokio_console ``` -You will also need to enable the `tokio_console` config option in Continuwuity when -starting it. This was due to tokio-console causing gradual memory leak/usage -if left enabled. +You will also need to enable the `tokio_console` config option in Continuwuity +when starting it. This was due to tokio-console causing gradual memory +leak/usage if left enabled. ## Building Docker Images -To build a Docker image for Continuwuity, use the standard Docker build command: +Official Continuwuity images are built using **Docker Buildx** and the +Dockerfile found at [`docker/Dockerfile`][dockerfile-path]. + +The images are compatible with Docker and other container runtimes like Podman +or containerd. + +The images _do not contain a shell_. They contain only the Continuwuity binary, +required libraries, TLS certificates, and metadata. + +
+Click to view the Dockerfile + +You can also + + + view the Dockerfile on Forgejo + +. + +```dockerfile file="../../docker/Dockerfile" -```bash -docker build -f docker/Dockerfile . ``` -The image can be cross-compiled for different architectures. +
+### Building Locally + +To build an image locally using Docker Buildx: + +```bash +# Build for the current platform and load into the local Docker daemon +docker buildx build --load --tag continuwuity:latest -f docker/Dockerfile . + +# Example: Build for specific platforms and push to a registry +# docker buildx build --platform linux/amd64,linux/arm64 --tag registry.io/org/continuwuity:latest -f docker/Dockerfile . --push + +# Example: Build binary optimised for the current CPU (standard release profile) +# docker buildx build --load \ +# --tag continuwuity:latest \ +# --build-arg TARGET_CPU=native \ +# -f docker/Dockerfile . + +# Example: Build maxperf variant (release-max-perf profile with LTO) +# docker buildx build --load \ +# --tag continuwuity:latest-maxperf \ +# --build-arg TARGET_CPU=native \ +# --build-arg RUST_PROFILE=release-max-perf \ +# -f docker/Dockerfile . +``` + +Refer to the Docker Buildx documentation for more advanced build options. + +[dockerfile-path]: + https://forgejo.ellis.link/continuwuation/continuwuation/src/branch/main/docker/Dockerfile [continuwuation-ruwuma]: https://forgejo.ellis.link/continuwuation/ruwuma [continuwuation-rocksdb]: https://forgejo.ellis.link/continuwuation/rocksdb -[continuwuation-jemallocator]: https://forgejo.ellis.link/continuwuation/jemallocator -[continuwuation-rustyline-async]: https://forgejo.ellis.link/continuwuation/rustyline-async -[continuwuation-rust-rocksdb]: https://forgejo.ellis.link/continuwuation/rust-rocksdb +[continuwuation-jemallocator]: + https://forgejo.ellis.link/continuwuation/jemallocator +[continuwuation-rustyline-async]: + https://forgejo.ellis.link/continuwuation/rustyline-async +[continuwuation-rust-rocksdb]: + https://forgejo.ellis.link/continuwuation/rust-rocksdb [continuwuation-tracing]: https://forgejo.ellis.link/continuwuation/tracing - [ruma]: https://github.com/ruma/ruma/ [rocksdb]: https://github.com/facebook/rocksdb/ [jemallocator]: https://github.com/tikv/jemallocator/ [rustyline-async]: https://github.com/zyansheep/rustyline-async/ [rust-rocksdb]: https://github.com/rust-rocksdb/rust-rocksdb/ [tracing]: https://github.com/tokio-rs/tracing/ - [7]: https://docs.rs/tokio-console/latest/tokio_console/ [8]: https://github.com/zaidoon1/ [9]: https://github.com/rust-lang/cargo/issues/12162 diff --git a/docs/reference/_meta.json b/docs/reference/_meta.json index 6d75c345..06f44267 100644 --- a/docs/reference/_meta.json +++ b/docs/reference/_meta.json @@ -4,6 +4,11 @@ "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 new file mode 100644 index 00000000..56bd411e --- /dev/null +++ b/docs/reference/environment-variables.mdx @@ -0,0 +1,281 @@ +# Environment Variables + +Continuwuity can be configured entirely through environment variables, making it +ideal for containerised deployments and infrastructure-as-code scenarios. + +This is a convenience reference and may not be exhaustive. The +[Configuration Reference](./config.mdx) is the primary source for all +configuration options. + +## Prefix System + +Continuwuity supports three environment variable prefixes for backwards +compatibility: + +- `CONTINUWUITY_*` (current, recommended) +- `CONDUWUIT_*` (compatibility) +- `CONDUIT_*` (legacy) + +All three prefixes work identically. Use double underscores (`__`) to represent +nested configuration sections from the TOML config. + +**Examples:** + +```bash +# Simple top-level config +CONTINUWUITY_SERVER_NAME="matrix.example.com" +CONTINUWUITY_PORT="8008" + +# Nested config sections use double underscores +# This maps to [database] section in TOML +CONTINUWUITY_DATABASE__PATH="/var/lib/continuwuity" + +# This maps to [tls] section in TOML +CONTINUWUITY_TLS__CERTS="/path/to/cert.pem" +``` + +## Configuration File Override + +You can specify a custom configuration file path: + +- `CONTINUWUITY_CONFIG` - Path to continuwuity.toml (current) +- `CONDUWUIT_CONFIG` - Path to config file (compatibility) +- `CONDUIT_CONFIG` - Path to config file (legacy) + +## 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