oss/conduit
oss/conduit
1
0
Fork 0
mirror of https://gitlab.com/famedly/conduit.git synced 2025-08-01 17:38:36 +00:00
Code Wiki Activity

docs: Use mdbook for docs

Browse source
This commit is contained in:
Jonas Zohren 2022-02-06 17:48:06 +01:00
parent 6e106b5732
commit 70b6890edd
No known key found for this signature in database
GPG key ID: FE3ED5D90A175463
14 changed files with 342 additions and 162 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/SUMMARY.md Normal file
View file

@ -0,0 +1,10 @@
# Summary
[Introduction](../README.md)
- [Deploy](deploy/_index.md)
- [Binary](deploy/binary.md)
- [Docker](deploy/docker.md)
- [Distro Packages](deploy/packages.md)
- [VoIP with TURN](turn.md)
- [Appservices](appservices.md)

7
docs/_getting_help.md Normal file
View file

@ -0,0 +1,7 @@
> ### ❔ Getting help
>
> If you run into any problems while setting up Conduit,
>
> - Write an email to `timo@koesters.xyz`,
> - Ask us in [#conduit:fachschaften.org](https://matrix.to/#/#conduit:fachschaften.org) or
> - [Open an issue on GitLab](https://gitlab.com/famedly/conduit/-/issues/new).

59
docs/appservices.md Normal file
View file

@ -0,0 +1,59 @@
# Setting up Appservices
{{#include _getting_help.md}}
## Set up the appservice - general instructions
Follow whatever instructions are given by the appservice. This usually includes
downloading, changing its config (setting domain, homeserver url, port etc.)
and later starting it.
At some point the appservice guide should ask you to add a registration yaml
file to the homeserver. In Synapse you would do this by adding the path to the
homeserver.yaml, but in Conduit you can do this from within Matrix:
First, go into the #admins room of your homeserver. The first person that
registered on the homeserver automatically joins it. Then send a message into
the room like this:
@conduit:your.server.name: register-appservice
```
paste
the
contents
of
the
yaml
registration
here
```
You can confirm it worked by sending a message like this:
`@conduit:your.server.name: list-appservices`
The @conduit bot should answer with `Appservices (1): your-bridge`
Then you are done. Conduit will send messages to the appservices and the
appservice can send requests to the homeserver. You don't need to restart
Conduit, but if it doesn't work, restarting while the appservice is running
could help.
## Appservice-specific instructions
### Remove an appservice
To remove an appservice go to your admin room and execute
`@conduit:your.server.name: unregister-appservice <name>`
where `<name>` one of the output of `list-appservices`.
### Tested appservices
These appservices have been tested and work with Conduit without any extra steps:
- [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord)
- [mautrix-hangouts](https://github.com/mautrix/hangouts/)
- [mautrix-telegram](https://github.com/mautrix/telegram/)
- [mautrix-signal](https://github.com/mautrix/signal/) from version `0.2.2` forward.
- [heisenbridge](https://github.com/hifi/heisenbridge/)

17
docs/deploy/_index.md Normal file
View file

@ -0,0 +1,17 @@
# Deploying Conduit
## 🦀 Binary
Conduit compiles to a single binary that can be copied and run on pretty much any Linux server.
[Read about how to use it here.](./binary.md)
## 🐳 Docker
The community created a guide to deploy Conduit with Docker or with Docker-Compose.
[You can read all about it here.](./docker.md)
## 📦 Distro Packages
[See how you can use native packages for Debian and NixOS](./packages.md)

240
docs/deploy/binary.md Normal file
View file

@ -0,0 +1,240 @@
## Installing Conduit with a binary
{{#include ../_getting_help.md}}
## Prerequisites
Although you might be able to compile Conduit for Windows, we do recommend running it on a Linux server.
This guide assumes you have root access to a Debian Linux server with at least 1 GB of available RAM and at least 10 GB of free disk space.
The more chats you join and the bigger these chats are, the more RAM and storage you'll need.
As Matrix uses HTTPS for communication, you'll also need a domain, like `matrix.org`. Whenever you see `your.server.name` in this guide, replace it with your actual domain.
## Download Conduit
You may simply download the binary that fits your machine. Run `uname -m` to see what you need. Now copy the right URL:
| CPU Architecture | Download stable version | Download development version |
| -------------------- | ------------------------------ | ---------------------------- |
| x84_64 / amd64 | [Download][x84_64-musl-master] | [Download][x84_64-musl-next] |
| armv6 | [Download][armv6-musl-master] | [Download][armv6-musl-next] |
| armv7 (Raspberry Pi) | [Download][armv7-musl-master] | [Download][armv7-musl-next] |
| armv8 / aarch64 | [Download][armv8-musl-master] | [Download][armv8-musl-next] |
[x84_64-musl-master]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-x86_64-unknown-linux-musl?job=build:release:cargo:x86_64-unknown-linux-musl
[armv6-musl-master]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-arm-unknown-linux-musleabihf?job=build:release:cargo:arm-unknown-linux-musleabihf
[armv7-musl-master]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-armv7-unknown-linux-musleabihf?job=build:release:cargo:armv7-unknown-linux-musleabihf
[armv8-musl-master]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-aarch64-unknown-linux-musl?job=build:release:cargo:aarch64-unknown-linux-musl
[x84_64-musl-next]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/next/raw/conduit-x86_64-unknown-linux-musl?job=build:release:cargo:x86_64-unknown-linux-musl
[armv6-musl-next]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/next/raw/conduit-arm-unknown-linux-musleabihf?job=build:release:cargo:arm-unknown-linux-musleabihf
[armv7-musl-next]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/next/raw/conduit-armv7-unknown-linux-musleabihf?job=build:release:cargo:armv7-unknown-linux-musleabihf
[armv8-musl-next]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/next/raw/conduit-aarch64-unknown-linux-musl?job=build:release:cargo:aarch64-unknown-linux-musl
```bash
sudo wget -O /usr/local/bin/matrix-conduit <url>
sudo chmod +x /usr/local/bin/matrix-conduit
```
## Or compile the binary yourself
If you don't want to use our prebuilt binaries, you can also compile Conduit yourself.
To do so, you'll need to install Rust and some dependencies:
```bash
sudo apt install git curl libclang-dev build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
If that succeeded, clone Conduit and build it:
```bash
git clone --depth 1 "https://gitlab.com/famedly/conduit.git" conduit && cd conduit
cargo build --release
sudo cp target/release/conduit /usr/local/bin/conduit
```
Note that this currently requires Rust 1.56, which should automatically be used when you installed Rust via rustup.
<details>
<summary>Cross-Compiling to different architectures</summary>
In theory, Rust offers smooth cross-compilation. But since Conduit is not pure-Rust (due to its database choices), you can't just `cargo build --target armv7-unknown-linux-musleabihf`.
But fear not, smart people (in this case, the wonderful [Maxim](@mdc:anter.io)) prepared some cross-images for you. So to cross-compile:
1. [Install Docker](https://docs.docker.com/get-docker/)
2. [Install cargo-cross](https://github.com/cross-rs/cross#installation)
3. Choose a target and compile with `cross build --target="YOUR_TARGET_HERE" --locked --release`
Currently supported targets are:
- `aarch64-unknown-linux-musl`
- `arm-unknown-linux-musleabihf`
- `armv7-unknown-linux-musleabihf`
- `x86_64-unknown-linux-musl`
</details>
## Adding a Conduit user
While Conduit can run as any user, it is usually better to use dedicated users for different services. This also allows
you to make sure that the file permissions are correctly set up.
In Debian, you can use this command to create a Conduit user:
```bash
sudo adduser --system conduit --no-create-home
```
## Setting up a systemd service
Now we'll set up a systemd service for Conduit, so it's easy to start/stop Conduit and set it to autostart when your
server reboots. Simply paste the default systemd service you can find below into
`/etc/systemd/system/conduit.service`.
```systemd
[Unit]
Description=Conduit Matrix Server
After=network.target
[Service]
Environment="CONDUIT_CONFIG=/etc/matrix-conduit/conduit.toml"
User=conduit
Group=nogroup
Restart=always
ExecStart=/usr/local/bin/matrix-conduit
[Install]
WantedBy=multi-user.target
```
Finally, run
```bash
sudo systemctl daemon-reload
```
## Creating the Conduit configuration file
Now we need to create the Conduit's config file in `/etc/matrix-conduit/conduit.toml`. Paste this in **and take a moment
to read it. You need to change at least the server name.**
```toml
{{#include ../../conduit-example.toml}}
```
## Setting the correct file permissions
As we are using a Conduit specific user, we need to allow it to read the config. To do that, you can run this command on
Debian:
```bash
sudo chown -R root:root /etc/matrix-conduit
sudo chmod 755 /etc/matrix-conduit
```
If you use the default database path, you also need to run this:
```bash
sudo mkdir -p /var/lib/matrix-conduit/
sudo chown -R conduit:nogroup /var/lib/matrix-conduit/
sudo chmod 700 /var/lib/matrix-conduit/
```
## Setting up the Reverse Proxy
This depends on whether you use Apache, Nginx or another web server.
### Apache
Create `/etc/apache2/sites-enabled/050-conduit.conf` and copy-and-paste this:
```apache
Listen 8448
<VirtualHost *:443 *:8448>
ServerName your.server.name # EDIT THIS
AllowEncodedSlashes NoDecode
ProxyPass /_matrix/ http://127.0.0.1:6167/_matrix/ nocanon
ProxyPassReverse /_matrix/ http://127.0.0.1:6167/_matrix/
</VirtualHost>
```
**You need to make some edits again.** When you are done, run
```bash
sudo systemctl reload apache2
```
### Nginx
If you use Nginx and not Apache, add the following server section inside the `http` section of `/etc/nginx/nginx.conf`
```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;
location /_matrix/ {
proxy_pass http://127.0.0.1:6167$request_uri;
proxy_set_header Host $http_host;
proxy_buffering off;
}
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;
}
```
**You need to make some edits again.** When you are done, run
```bash
sudo systemctl reload nginx
```
## SSL Certificate
The easiest way to get an SSL certificate, if you don't have one already, is to install `certbot` and run this:
```bash
sudo certbot -d your.server.name
```
## You're done!
Now you can start Conduit with:
```bash
sudo systemctl start conduit
```
Set it to start automatically when your system boots with:
```bash
sudo systemctl enable conduit
```
## How do I know it works?
You can open <https://app.element.io>, enter your homeserver and try to register.
You can also use these commands as a quick health check.
```bash
curl https://your.server.name/_matrix/client/versions
curl https://your.server.name:8448/_matrix/client/versions
```
- To check if your server can talk with other homeservers, you can use the [Matrix Federation Tester](https://federationtester.matrix.org/)
- If you want to set up an Appservice, take a look at the [Appservice Guide](../appservices.md).

169
docs/deploy/docker.md Normal file
View file

@ -0,0 +1,169 @@
# Deploy using Docker
{{#include ../_getting_help.md}}
> **Note:** To run and use Conduit you should probably use it with a Domain or Subdomain behind a reverse proxy (like Nginx, Traefik, Apache, ...) with a Lets Encrypt certificate.
### Get the image
[![Image Size][shield]][dh] [![Image pulls][pulls]][dh]
You can download the latest release version of Conduit as a pre-built multi-arch docker image from [Docker Hub][dh]:
```bash
docker pull matrixconduit/matrix-conduit:latest
```
If you are feeling adventurous, you can also use the unstable, in-development version:
```bash
docker pull matrixconduit/matrix-conduit:next
```
[dh]: https://hub.docker.com/r/matrixconduit/matrix-conduit
[shield]: https://img.shields.io/docker/image-size/matrixconduit/matrix-conduit/latest
[pulls]: https://img.shields.io/docker/pulls/matrixconduit/matrix-conduit
\
<details>
<summary>Want to build your own image?</summary>
Clone the repo and enter it:
```bash
git clone --depth 1 https://gitlab.com/famedly/conduit.git
cd conduit
```
Then, build the image:
```bash
docker build --tag matrixconduit/matrix-conduit:latest .
```
> ⏳ This can take quite some time, as it does a full release build. Depending on your hardware, this may take between 15 and 60 minutes.
If you want to change the userid:groupid under which Conduit will run in the container, you can customize them with build args:
```bash
docker build \
--build-arg USER_ID=1000 \
--build-arg GROUP_ID=1000 \
--tag matrixconduit/matrix-conduit:latest .
```
By default, `USER_ID` and `GROUP_ID` are both set to `1000`.
</details>
### Run
```bash
docker run -d -p 6167:6167 \
-v db:/var/lib/matrix-conduit/ \
-e CONDUIT_SERVER_NAME="your.server.name" \
-e CONDUIT_DATABASE_BACKEND="rocksdb" \
-e CONDUIT_ALLOW_REGISTRATION="true" \
-e CONDUIT_ALLOW_FEDERATION="true" \
-e CONDUIT_MAX_REQUEST_SIZE="20_000_000" \
-e CONDUIT_TRUSTED_SERVERS='[\"matrix.org\"]' \
-e CONDUIT_MAX_CONCURRENT_REQUESTS="100" \
-e CONDUIT_LOG="info,rocket=off,_=off,sled=off" \
--name "conduit" \
matrixconduit/matrix-conduit:latest
```
The `-d` flag lets the container run in detached mode.
> ⚠️ When running Conduit with docker, you are expected to configure it only with environment variables, not via a config.toml.
>
> Where you would use `server_name` in the config.toml, use `CONDUIT_SERVER_NAME` as the env var.
If you just want to test Conduit for a short time, you can also supply the `--rm` flag, which will clean up everything related to your container after you stop it.
## Docker-compose
If the `docker run` command is not for you or your setup, you can also use one of the provided `docker-compose` files.
Depending on your proxy setup, you can use one of the following files;
- If you already have a `traefik` instance set up, use [`docker-compose.for-traefik.yml`](docker-compose.for-traefik.yml)
- If you don't have a `traefik` instance set up (or any other reverse proxy), use [`docker-compose.with-traefik.yml`](docker-compose.with-traefik.yml)
- For any other reverse proxy, use [`docker-compose.yml`](docker-compose.yml)
When picking the traefik-related compose file, rename it, so it matches `docker-compose.yml`, and
rename the override file to `docker-compose.override.yml`. Edit the latter with the values you want
for your server.
Additional info about deploying Conduit can be found [here](../DEPLOY.md).
### Build
To build the Conduit image with docker-compose, you first need to open and modify the `docker-compose.yml` file. There you need to comment the `image:` option and uncomment the `build:` option. Then call docker-compose with:
```bash
docker-compose up
```
This will also start the container right afterwards, so if want it to run in detached mode, you also should use the `-d` flag.
### Run
If you already have built the image or want to use one from the registries, you can just start the container and everything else in the compose file in detached mode with:
```bash
docker-compose up -d
```
> **Note:** Don't forget to modify and adjust the compose file to your needs.
### Use Traefik as Proxy
As a container user, you probably know about Traefik. It is an easy to use reverse proxy for making
containerized app and services available through the web. With the two provided files,
[`docker-compose.for-traefik.yml`](docker-compose.for-traefik.yml) (or
[`docker-compose.with-traefik.yml`](docker-compose.with-traefik.yml)) and
[`docker-compose.override.yml`](docker-compose.override.traefik.yml), it is equally easy to deploy
and use Conduit, with a little caveat. If you already took a look at the files, then you should have
seen the `well-known` service, and that is the little caveat. Traefik is simply a proxy and
loadbalancer and is not able to serve any kind of content, but for Conduit 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 will serve those two files.
So... step by step:
1. Copy [`docker-compose.traefik.yml`](docker-compose.traefik.yml) and [`docker-compose.override.traefik.yml`](docker-compose.override.traefik.yml) from the repository and remove `.traefik` from the filenames.
2. Open both files and modify/adjust them to your needs. Meaning, change the `CONDUIT_SERVER_NAME` and the volume host mappings according to your needs.
3. Configure Conduit per env vars.
4. Uncomment the `element-web` service if you want to host your own Element Web Client and create a `element_config.json`.
5. Create the files needed by the `well-known` service.
- `./nginx/matrix.conf` (relative to the compose file, you can change this, but then also need to change the volume mapping)
```nginx
server {
server_name <SUBDOMAIN>.<DOMAIN>;
listen 80 default_server;
location /.well-known/matrix/server {
return 200 '{"m.server": "<SUBDOMAIN>.<DOMAIN>:443"}';
add_header Content-Type application/json;
}
location /.well-known/matrix/client {
return 200 '{"m.homeserver": {"base_url": "https://<SUBDOMAIN>.<DOMAIN>"}}';
add_header Content-Type application/json;
add_header "Access-Control-Allow-Origin" *;
}
location / {
return 404;
}
}
```
6. Run `docker-compose up -d`
7. Connect to your homeserver with your preferred client and create a user. You should do this immediately after starting Conduit, because the first created user is the admin.

45
docs/deploy/packages.md Normal file
View file

@ -0,0 +1,45 @@
# Distribution Packages
> These packages are not maintained by the Conduit maaintainers. They are third-party community contributions we have no control over.
## Debian
[Paul](https://wiki.debian.org/PaulVanTilburg) has done work on preparing Conduit for Debian packaging. See the [Debian directory](https://gitlab.com/famedly/conduit/-/tree/next/debian) for more info about this.
```bash
# You'll need cargo-deb to create a debian package:
cargo install cargo-deb
# Run this in the Conduit repo to compile and create a package:
cargo deb
```
## NixOS
[![nixpkgs unstable package](https://repology.org/badge/version-for-repo/nix_unstable/matrix-conduit.svg)](https://repology.org/project/matrix-conduit/versions)
[PimEyes](https://github.com/pimeys) has packaged
[Conduit for NixOS](https://search.nixos.org/packages?channel=unstable&show=matrix-conduit&from=0&size=50&sort=relevance&type=packages&query=matrix-conduit).
```bash
nix-env -iA nixos.matrix-conduit
```
## FreBSD Ports
[![FreeBSD port](https://repology.org/badge/version-for-repo/freebsd/matrix-conduit.svg)](https://repology.org/project/matrix-conduit/versions)
Apparently, there is also a [FreeBSD Port of Conduit](https://www.freshports.org/net-im/conduit).
```bash
cd /usr/ports/net-im/conduit/ && make install clean
```
## Void Linux
[![Void Linux x86_64 package](https://repology.org/badge/version-for-repo/void_x86_64/matrix-conduit.svg)](https://repology.org/project/matrix-conduit/versions)
[Joel Beckmeyer](https://github.com/TinfoilSubmarine) carefully brought a [Void Linux package for Conduit](https://github.com/void-linux/void-packages/blob/master/srcpkgs/conduit/template) to life.
```bash
xbps-install -S conduit
```

33
docs/turn.md Normal file
View file

@ -0,0 +1,33 @@
# Setting up TURN/STURN
{{#include _getting_help.md}}
## General instructions
- It is assumed you have a [Coturn server](https://github.com/coturn/coturn) up and running. See [Synapse reference implementation](https://github.com/matrix-org/synapse/blob/e3fe6347be1da930b6a0ed2005b565369800a327/docs/turn-howto.md).
## Edit/Add a few settings to your existing conduit.toml
```toml
# Refer to your Coturn settings.
# `your.turn.url` has to match the REALM setting of your Coturn as well as `transport`.
turn_uris = ["turn:your.turn.url?transport=udp", "turn:your.turn.url?transport=tcp"]
# static-auth-secret of your turnserver
turn_secret = "ADD SECRET HERE"
# If you have your TURN server configured to use a username and password
# you can provide these information too. In this case comment out `turn_secret above`!
#turn_username = ""
#turn_password = ""
```
You can generate a secret by running the following command on Linux:
```bash
openssl rand -base64 33
```
## Apply settings
Restart Conduit.