Conduit Documentation

repository·next·Indexed 20 days ago

Conduit is a high-performance, lightweight Matrix homeserver written in Rust, designed for easy deployment on devices ranging from Raspberry Pis to corporate servers. This documentation covers installation on Debian, systemd service management, and detailed configuration for network settings, database backends (SQLite or RocksDB), S3 and FileSystem media storage, TURN server relaying, proxy modes, and comprehensive rate limiting presets for client and federation APIs.

Tokens: 22K
Snippets: 92
Records: 150
Agent score: 69%

What's inside Conduit

Overview of Conduit
next
Conduit is an efficient Matrix homeserver written in Rust. It is designed to be easy to set up and lightweight enough to run on small devices like a Raspberry Pi, making it suitable for hosting Matrix for families, friends, or companies.
Current Status: Conduit is currently in Beta. While most Matrix rooms can be joined, some features are still under development, including:
- E2EE emoji comparison over federation (though E2EE chat itself works).
- Outgoing read receipts, typing, and presence over federation (incoming works).
https://github.com/timokoesters/conduit/blob/next/README.md
How rate limiting overrides work
next
Rate limiting in Conduit is implemented using a leaky bucket algorithm. Each restriction consists of a burst_capacity (the maximum allowed amount at once) and a timeframe (the rate at which the bucket empties).
When overriding a preset, you must specify both the timeframe and the burst capacity. The configuration hierarchy is structured as follows:
1. API Type: client (Client-Server API) or federation (Server-Server API).
2. Scope: global (applies to all clients) or target (applies to individual clients).
3. Restriction Type: request (number of requests) or media (number of bytes).
Targets are identified by User ID, Server Name (domain), Appservice ID, or IP address.
https://github.com/timokoesters/conduit/blob/next/docs/configuration/rate-limiting.md
Override request restrictions
next
To override specific endpoint limits, use the path [global.rate_limiting.<client|federation>.<global|target>.<restriction>]. For request restrictions, both burst_capacity and a per_<second|minute|hour|day> key must be provided as integers representing the number of requests.
Examples:
- Limit registration to 1 per hour with a burst of 4 for individual targets:
```
[global.rate_limiting.client.target.registration]
per_hour = 1
burst_capacity = 4
```
- Limit federation invites to 2 per minute with a burst of 15 for individual targets:
```
[global.rate_limiting.federation.target.invite]
per_minute = 2
burst_capacity = 15
```
- Limit global media downloads to 1 per second with a burst of 50:
```
[global.rate_limiting.client.global.media_download]
per_second = 1
burst_capacity = 50
```
```
[global.rate_limiting.client.target.registration]
per_hour = 1
burst_capacity = 4

[global.rate_limiting.federation.target.invite]
per_minute = 2
burst_capacity = 15

[global.rate_limiting.client.global.media_download]
per_second = 1
burst_capacity = 50
```
https://github.com/timokoesters/conduit/blob/next/docs/configuration/rate-limiting.md

Pull Conduit OCI images from registries

You can pull pre-built Conduit images from GitLab or Docker Hub. The latest tags are recommended for stable environments, while next tags are for development versions.

Registry	Image	Notes
GitLab Registry	`registry.gitlab.com/famedly/conduit/matrix-conduit:latest`	Stable
Docker Hub	`docker.io/matrixconduit/matrix-conduit:latest`	Stable
GitLab Registry	`registry.gitlab.com/famedly/conduit/matrix-conduit:next`	Development
Docker Hub	`docker.io/matrixconduit/matrix-conduit:next`	Development

docker image pull <image_link>

Deactivate a user and purge their media
next
When deactivating a user, you can automatically purge all media they have uploaded by using the --purge-media flag with the deactivate-user or deactivate-all commands.
```
deactivate-user --purge-media <user_id>
```
https://github.com/timokoesters/conduit/blob/next/docs/administration/media.md
Deploy Conduit using Docker Compose
next
Conduit provides several Docker Compose files depending on your reverse proxy setup:
- Existing Traefik instance: Use docker-compose.for-traefik.yml.
- No existing proxy (includes Traefik): Use docker-compose.with-traefik.yml.
- Other reverse proxies (Nginx, Apache, etc.): Use docker-compose.yml.
Building with Compose
To build the image using Compose, modify docker-compose.yml to comment out the image: option and uncomment the build: option, then run:
```
docker compose up
```
Running with Compose
If the image is already built or pulled, start the services in detached mode:
```
docker compose up -d
```
https://github.com/timokoesters/conduit/blob/next/docs/deploying/docker.md
Register an Appservice in Conduit
next
Unlike Synapse, which requires editing a homeserver.yaml file, Conduit allows you to register Appservices directly from within Matrix.
1. Join the #admins room of your homeserver (the first user to register on the server is automatically joined to this room).
2. Send a message to the Conduit bot using the register-appservice command, followed by the contents of your Appservice's registration YAML file.
Example command format: @conduit:your.server.name: register-appservice <paste yaml contents here>
After registration, Conduit will begin sending messages to the Appservice, and the Appservice will be able to send requests to the homeserver. A restart of Conduit may be required if the Appservice does not immediately respond, provided the Appservice itself is already running.
```
@conduit:your.server.name: register-appservice
paste
the
contents
of
the
yaml
registration
here
```
https://github.com/timokoesters/conduit/blob/next/docs/appservices.md

Set up an Nginx Reverse Proxy for Conduit

Add the following server block inside the http section of /etc/nginx/nginx.conf.

Important Edits:

server_name: Set to your domain.
ssl_certificate paths: Set to your actual Let's Encrypt paths.
client_max_body_size: Set to 20M (or higher) to allow large file uploads.

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    listen 8448 ssl http2;
    listen [::]:8448 ssl http2;
    server_name your.server.name; # EDIT THIS
    merge_slashes off;

    # Nginx defaults to only allow 1MB uploads
    # Increase this to allow posting large files such as videos
    client_max_body_size 20M;

    location /_matrix/ {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_buffering off;
        proxy_read_timeout 5m;
    }

    ssl_certificate /etc/letsencrypt/live/your.server.name/fullchain.pem; # EDIT THIS
    ssl_certificate_key /etc/letsencrypt/live/your.server.name/privkey.pem; # EDIT THIS
    ssl_trusted_certificate /etc/letsencrypt/live/your.server.name/chain.pem; # EDIT THIS
    include /etc/letsencrypt/options-ssl-nginx.conf;
}

After configuring, reload Nginx:

$ sudo systemctl reload nginx

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    listen 8448 ssl http2;
    listen [::]:8448 ssl http2;
    server_name your.server.name; # EDIT THIS
    merge_slashes off;

    client_max_body_size 20M;

    location /_matrix/ {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_buffering off;
        proxy_read_timeout 5m;
    }

    ssl_certificate /etc/letsencrypt/live/your.server.name/fullchain.pem; # EDIT THIS
    ssl_certificate_key /etc/letsencrypt/live/your.server.name/privkey.pem; # EDIT THIS
    ssl_trusted_certificate /etc/letsencrypt/live/your.server.name/chain.pem; # EDIT THIS
    include /etc/letsencrypt/options-ssl-nginx.conf;
}

Use the latest Conduit code with the NixOS module
next
If you need to run the latest development version of Conduit instead of the version provided by Nixpkgs, you can override the package used by the NixOS service.
1. Obtain the latest Conduit code via the flake.nix or default.nix at the root of the Conduit repository.
2. Set the services.matrix-conduit.package option in your NixOS configuration to point to your custom Conduit package.
https://github.com/timokoesters/conduit/blob/next/docs/deploying/nixos.md
Make a user an admin
next
To grant administrative privileges to a user, invite them to the admin room. Once they have joined the room, they can manage the server by interacting with the @conduit:<server_name> user.
https://github.com/timokoesters/conduit/blob/next/docs/faq.md
Delete media from a specific remote server
next
If you encounter undesirable media originating from a different Matrix server, use the purge-media-from-server command to remove that media from your media backend. After purging, it is recommended to contact the remote server administrator so they can address the offending user(s).
```
purge-media-from-server <server_name>
```
https://github.com/timokoesters/conduit/blob/next/docs/administration/media.md
Use the Complement automation script with Conduit
next
To automate the use of Complement with Conduit, use the automation script located at ../bin/complement. This script accepts several command-line arguments to facilitate the integration. For a complete list of available arguments and specific usage instructions, you should inspect the contents of the script file directly.
```
# Usage depends on specific arguments defined within the script
../bin/complement [ARGUMENTS]
```
https://github.com/timokoesters/conduit/blob/next/complement/README.md

Conduit Documentation

What's inside Conduit

Building with Compose

Running with Compose