TudbuT/conduit
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored
View file

@ -59,6 +59,8 @@ $RECYCLE.BIN/
# Conduit
conduit.toml
conduit.db
public/
index.html
# Etc.
**/*.rs.bk

70
.gitlab-ci.yml
View file

@ -1,8 +1,8 @@
stages:
- build
- build docker image
- docker
- test
- upload artifacts
- publish
variables:
GIT_SUBMODULE_STRATEGY: recursive
@ -145,7 +145,7 @@ build:debug:cargo:x86_64-unknown-linux-musl:
# --------------------------------------------------------------------- #
.docker-shared-settings:
stage: "build docker image"
stage: "docker"
image: jdrouet/docker-with-buildx:stable
tags: ["docker"]
services:
@ -353,7 +353,7 @@ test:dockerlint:
# --------------------------------------------------------------------- #
publish:package:
stage: "upload artifacts"
stage: publish
needs:
- "build:release:cargo:x86_64-unknown-linux-musl"
- "build:release:cargo:arm-unknown-linux-musleabihf"
@ -375,6 +375,68 @@ publish:package:
- 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file conduit-armv7-unknown-linux-musleabihf "${BASE_URL}/conduit-armv7-unknown-linux-musleabihf"'
- 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file conduit-aarch64-unknown-linux-musl "${BASE_URL}/conduit-aarch64-unknown-linux-musl"'
# --------------------------------------------------------------------- #
# Docs testing and publishing #
# --------------------------------------------------------------------- #
build:docs:
stage: build
needs: []
image: "registry.gitlab.com/jfowl/conduit-containers/rust-with-tools:latest"
tags: ["docker"]
interruptible: true
script:
- echo "$CI_MERGE_REQUEST_ID"
- mdbook build --dest-dir ./public
artifacts:
paths:
- public
expire_in: 2 weeks
.publish-docs-shared-settings:
stage: publish
needs:
- "build:docs"
image: "registry.gitlab.com/jfowl/conduit-containers/surge-uploader:latest"
tags: ["docker"]
interruptible: true
variables:
GIT_STRATEGY: "none" # Don't need a clean copy of the code, we just operate on artifacts
script:
- npx surge $CI_PROJECT_DIR/public $CI_ENVIRONMENT_URL
publish:docs:mrs:
extends: .publish-docs-shared-settings
environment:
name: docs/review/$CI_COMMIT_REF_SLUG
url: https://conduit-docs-$CI_COMMIT_REF_SLUG.surge.sh
rules:
- if: "$SURGE_TOKEN && $CI_MERGE_REQUEST_ID"
publish:docs:next:
extends: .publish-docs-shared-settings
environment:
name: docs/next
url: https://conduit-docs-next.surge.sh
rules:
- if: '$SURGE_TOKEN && ($CI_COMMIT_BRANCH == "next")'
publish:docs:master:
extends: .publish-docs-shared-settings
environment:
name: docs/master
url: https://conduit-docs.surge.sh
rules:
- if: '$SURGE_TOKEN && ($CI_COMMIT_BRANCH == "master")'
publish:docs:tags:
extends: .publish-docs-shared-settings
environment:
name: docs/$CI_COMMIT_TAG
url: https://conduit-docs-$CI_COMMIT_REF_SLUG.surge.sh
rules:
- if: "$SURGE_TOKEN && $CI_COMMIT_TAG"
# Avoid duplicate pipelines
# See: https://docs.gitlab.com/ee/ci/yaml/workflow.html#switch-between-branch-pipelines-and-merge-request-pipelines
workflow:

3
.gitlab/route-map.yml Normal file
View file

@ -0,0 +1,3 @@
# Docs: Map markdown to html files
- source: /docs/(.+)\.md/
public: '\1.html'

2
Cargo.toml
View file

@ -114,7 +114,7 @@ path = "src/lib.rs"
[package.metadata.deb]
name = "matrix-conduit"
maintainer = "Paul van Tilburg <paul@luon.net>"
copyright = "2020, Timo Kösters <timo@koesters.xyz>"
copyright = "2022, Timo Kösters <timo@koesters.xyz>"
license-file = ["LICENSE", "3"]
depends = "$auto, ca-certificates"
extended-description = """\

65
README.md
View file

@ -1,26 +1,39 @@
# Conduit
# ⚡️ Conduit
### A Matrix homeserver written in Rust
### An efficient Matrix homeserver written in Rust
#### What is the goal?
## 🚀 Get started
You can find all the details on how to set up and manage your Conduit server in the **[Documentation](https://conduit-docs.surge.sh)**
## ❔ FAQ
<details open>
<summary>What is the goal?</summary>
An efficient Matrix homeserver that's easy to set up and just works. You can install
it on a mini-computer like the Raspberry Pi to host Matrix for your family,
friends or company.
#### Can I try it out?
</details>
<details>
<summary>Can I try it out?</summary>
Yes! You can test our Conduit instance by opening a Matrix client (<https://app.element.io> or Element Android for
example) and registering on the `conduit.rs` homeserver.
It is hosted on a ODROID HC 2 with 2GB RAM and a SAMSUNG Exynos 5422 CPU, which
was used in the Samsung Galaxy S5. It joined many big rooms including Matrix
was used in the Samsung Galaxy S5. It joined many big rooms, including Matrix
HQ.
#### What is the current status?
</details>
<details>
<summary>What is the current status?</summary>
Conduit is Beta, meaning you can join and participate in most
Matrix rooms, but not all features are supported and you might run into bugs
Matrix rooms, but not all features are supported, and you might run into bugs
from time to time.
There are still a few important features missing:
@ -30,38 +43,28 @@ There are still a few important features missing:
Check out the [Conduit 1.0 Release Milestone](https://gitlab.com/famedly/conduit/-/milestones/3).
#### How can I deploy my own?
</details>
- Simple install (this was tested the most): [DEPLOY.md](DEPLOY.md)
- Debian package: [debian/README.Debian](debian/README.Debian)
- Docker: [docker/README.md](docker/README.md)
## 💻 How to contribute
If you want to connect an Appservice to Conduit, take a look at [APPSERVICES.md](APPSERVICES.md).
1. Look for an [issue](https://gitlab.com/famedly/conduit/-/issues) you would like to work on and make sure it's not assigned to other users
2. Ask someone to assign the issue to you (comment on the issue or chat in [#conduit:fachschaften.org](https://matrix.to/#/#conduit:fachschaften.org))
3. [Fork the repo](https://gitlab.com/famedly/conduit/-/forks/new) and work on the issue. [#conduit:fachschaften.org](https://matrix.to/#/#conduit:fachschaften.org) is happy to help :)
4. Submit a merge request
#### How can I contribute?
## 🤗 Thanks to
1. Look for an issue you would like to work on and make sure it's not assigned
to other users
2. Ask someone to assign the issue to you (comment on the issue or chat in
[#conduit:fachschaften.org](https://matrix.to/#/#conduit:fachschaften.org))
3. Fork the repo and work on the issue.[#conduit:fachschaften.org](https://matrix.to/#/#conduit:fachschaften.org) is happy to help :)
4. Submit a MR
#### Thanks to
Thanks to Famedly, Prototype Fund (DLR and German BMBF) and all other individuals for financially supporting this project.
Thanks to [Famedly](https://famedly.com/), [Prototype Fund](https://prototypefund.de/) (DLR and German BMBF) and all other individuals for financially supporting this project.
Thanks to the contributors to Conduit and all libraries we use, for example:
- Ruma: A clean library for the Matrix Spec in Rust
- axum: A modular web framework
- [Ruma](https://github.com/ruma/ruma): A clean library for the Matrix Spec in Rust
- [Axum](https://docs.rs/axum/latest/axum/): A modular web framework
#### Donate
## 💸 Donate
Liberapay: <https://liberapay.com/timokoesters/>\
Bitcoin: `bc1qnnykf986tw49ur7wx9rpw2tevpsztvar5x8w4n`
If you want to support the project, you can donate to Timo, the maintainer via [Liberapay](https://liberapay.com/timokoesters/) or Bitcoin (`bc1qnnykf986tw49ur7wx9rpw2tevpsztvar5x8w4n`)
#### Logo
## ⚡️ Logo
Lightning Bolt Logo: https://github.com/mozilla/fxemoji/blob/gh-pages/svgs/nature/u26A1-bolt.svg \
Logo License: https://github.com/mozilla/fxemoji/blob/gh-pages/LICENSE.md
The Conduit Lightning Bolt logo is courtesy of [Mozilla FxEmojis](https://github.com/mozilla/fxemoji/blob/gh-pages/svgs/nature/u26A1-bolt.svg) ([CC BY 4.0](https://github.com/mozilla/fxemoji/blob/gh-pages/LICENSE.md))

16
book.toml Normal file
View file

@ -0,0 +1,16 @@
[book]
title = "Matrix Conduit"
author = "The Conduit contributors"
description = "Conduit is a simple, fast and reliable chat server for the Matrix protocol"
language = "en"
src = "docs"
[rust]
edition = "2021"
[build]
build-dir = "public"
create-missing = true
[output.html.search]
limit-results = 15

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).

4
APPSERVICES.md → docs/appservices.md
View file

@ -1,8 +1,6 @@
# Setting up Appservices
## Getting help
If you run into any problems while setting up an Appservice, 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).
{{#include _getting_help.md}}
## Set up the appservice - general instructions

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)

154
DEPLOY.md → docs/deploy/binary.md
View file

@ -1,23 +1,26 @@
# Deploying Conduit
## Installing Conduit with a binary
> ## 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` or [open an issue on GitLab](https://gitlab.com/famedly/conduit/-/issues/new).
{{#include ../_getting_help.md}}
## Installing Conduit
## Prerequisites
Although you might be able to compile Conduit for Windows, we do recommend running it on a linux server. We therefore
only offer Linux binaries.
Although you might be able to compile Conduit for Windows, we do recommend running it on a Linux server.
You may simply download the binary that fits your machine. Run `uname -m` to see what you need. Now copy the right url:
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.
| CPU Architecture | Download stable version | Download development version |
| ------------------------------------------- | ------------------------------ | ---------------------------- |
| x84_64 / amd64 (Most servers and computers) | [Download][x84_64-musl-master] | [Download][x84_64-musl-next] |
| armv6 | [Download][armv6-musl-master] | [Download][armv6-musl-next] |
| armv7 (e.g. Raspberry Pi by default) | [Download][armv7-musl-master] | [Download][armv7-musl-next] |
| armv8 / aarch64 | [Download][armv8-musl-master] | [Download][armv8-musl-next] |
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
@ -29,30 +32,57 @@ You may simply download the binary that fits your machine. Run `uname -m` to see
[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
sudo wget -O /usr/local/bin/matrix-conduit <url>
sudo chmod +x /usr/local/bin/matrix-conduit
```
Alternatively, you may compile the binary yourself
## 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 libclang-dev build-essential
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
$ cargo build --release
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.50.
Note that this currently requires Rust 1.56, which should automatically be used when you installed Rust via rustup.
If you want to cross compile Conduit to another architecture, read the [Cross-Compile Guide](cross/README.md).
<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
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:
In Debian, you can use this command to create a Conduit user:
```bash
sudo adduser --system conduit --no-create-home
@ -83,7 +113,7 @@ WantedBy=multi-user.target
Finally, run
```bash
$ sudo systemctl daemon-reload
sudo systemctl daemon-reload
```
## Creating the Conduit configuration file
@ -92,53 +122,12 @@ Now we need to create the Conduit's config file in `/etc/matrix-conduit/conduit.
to read it. You need to change at least the server name.**
```toml
[global]
# The server_name is the pretty name of this server. It is used as a suffix for user
# and room ids. Examples: matrix.org, conduit.rs
# The Conduit server needs all /_matrix/ requests to be reachable at
# https://your.server.name/ on port 443 (client-server) and 8448 (federation).
# If that's not possible for you, you can create /.well-known files to redirect
# requests. See
# https://matrix.org/docs/spec/client_server/latest#get-well-known-matrix-client
# and
# https://matrix.org/docs/spec/server_server/r0.1.4#get-well-known-matrix-server
# for more information
# YOU NEED TO EDIT THIS
#server_name = "your.server.name"
# This is the only directory where Conduit will save its data
database_path = "/var/lib/matrix-conduit/"
database_backend = "rocksdb"
# The port Conduit will be running on. You need to set up a reverse proxy in
# your web server (e.g. apache or nginx), so all requests to /_matrix on port
# 443 and 8448 will be forwarded to the Conduit instance running on this port
# Docker users: Don't change this, you'll need to map an external port to this.
port = 6167
# Max size for uploads
max_request_size = 20_000_000 # in bytes
# Enables registration. If set to false, no users can register on this server.
allow_registration = true
allow_federation = true
trusted_servers = ["matrix.org"]
#max_concurrent_requests = 100 # How many requests Conduit sends to other servers at the same time
#log = "info,state_res=warn,rocket=off,_=off,sled=off"
address = "127.0.0.1" # This makes sure Conduit can only be reached using the reverse proxy
#address = "0.0.0.0" # If Conduit is running in a container, make sure the reverse proxy (ie. Traefik) can reach it.
{{#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
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
@ -146,7 +135,7 @@ 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:
If you use the default database path, you also need to run this:
```bash
sudo mkdir -p /var/lib/matrix-conduit/
@ -179,12 +168,12 @@ ProxyPassReverse /_matrix/ http://127.0.0.1:6167/_matrix/
**You need to make some edits again.** When you are done, run
```bash
$ sudo systemctl reload apache2
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`
If you use Nginx and not Apache, add the following server section inside the `http` section of `/etc/nginx/nginx.conf`
```nginx
server {
@ -211,7 +200,7 @@ server {
**You need to make some edits again.** When you are done, run
```bash
$ sudo systemctl reload nginx
sudo systemctl reload nginx
```
## SSL Certificate
@ -219,7 +208,7 @@ $ sudo systemctl reload nginx
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
sudo certbot -d your.server.name
```
## You're done!
@ -227,13 +216,13 @@ $ sudo certbot -d your.server.name
Now you can start Conduit with:
```bash
$ sudo systemctl start conduit
sudo systemctl start conduit
```
Set it to start automatically when your system boots with:
```bash
$ sudo systemctl enable conduit
sudo systemctl enable conduit
```
## How do I know it works?
@ -243,18 +232,9 @@ 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
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/)
# What's next?
## Audio/Video calls
For Audio/Video call functionality see the [TURN Guide](TURN.md).
## Appservices
If you want to set up an appservice, take a look at the [Appservice Guide](APPSERVICES.md).
- If you want to set up an Appservice, take a look at the [Appservice Guide](../appservices.md).

93
docker/README.md → docs/deploy/docker.md
View file

@ -1,69 +1,98 @@
# 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.
## Docker
### Get the image
### Build & Dockerfile
[![Image Size][shield]][dh] [![Image pulls][pulls]][dh]
The Dockerfile provided by Conduit has two stages, each of which creates an image.
You can download the latest release version of Conduit as a pre-built multi-arch docker image from [Docker Hub][dh]:
1. **Builder:** Builds the binary from local context or by cloning a git revision from the official repository.
2. **Runner:** Copies the built binary from **Builder** and sets up the runtime environment, like creating a volume to persist the database and applying the correct permissions.
```bash
docker pull matrixconduit/matrix-conduit:latest
```
To build the image you can use the following command
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 .
```
which also will tag the resulting image as `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
After building the image you can simply run it with
```bash
docker run -d -p 8448:6167 \
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_ALLOW_REGISTRATION="true" \
-e CONDUIT_ALLOW_FEDERATION="true" \
-e CONDUIT_MAX_REQUEST_SIZE="20_000_000" \
-e CONDUIT_TRUSTED_SERVERS="[\"matrix.org\"]" \
-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
--name "conduit" \
matrixconduit/matrix-conduit:latest
```
or you can skip the build step and pull the image from one of the following registries:
The `-d` flag lets the container run in detached mode.
| Registry | Image | Size |
| --------------- | --------------------------------------------------------------- | --------------------- |
| Docker Hub | [matrixconduit/matrix-conduit:latest][dh] | ![Image Size][shield] |
| GitLab Registry | [registry.gitlab.com/famedly/conduit/matrix-conduit:latest][gl] | ![Image Size][shield] |
> ⚠️ 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.
[dh]: https://hub.docker.com/r/matrixconduit/matrix-conduit
[gl]: https://gitlab.com/famedly/conduit/container_registry/2497937
[shield]: https://img.shields.io/docker/image-size/matrixconduit/matrix-conduit/latest
The `-d` flag lets the container run in detached mode. You now need to supply a `conduit.toml` config file, an example can be found [here](../conduit-example.toml).
You can pass in different env vars to change config values on the fly. You can even configure Conduit completely by using env vars, but for that you need
to pass `-e CONDUIT_CONFIG=""` into your container. For an overview of possible values, please take a look at the `docker-compose.yml` file.
If you just want to test Conduit for a short time, you can use the `--rm` flag, which will clean up everything related to your container after you stop it.
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
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.
@ -91,7 +120,7 @@ docker-compose up -d
### Use Traefik as Proxy
As a container user, you probably know about Traefik. It is a easy to use reverse proxy for making
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
@ -104,11 +133,11 @@ either expose ports `443` and `8448` or serve two endpoints `.well-known/matrix/
With the service `well-known` we use a single `nginx` container that will serve those two files.
So...step by step:
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. Create the `conduit.toml` config file, an example can be found [here](../conduit-example.toml), or set `CONDUIT_CONFIG=""` and configure Conduit per env vars.
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.

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

16
TURN.md → docs/turn.md
View file

@ -1,13 +1,15 @@
# 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/develop/docs/turn-howto.md).
- 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
```
# Refer to your Coturn settings.
```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"]
@ -20,6 +22,12 @@ turn_secret = "ADD SECRET HERE"
#turn_password = ""
```
You can generate a secret by running the following command on Linux:
```bash
openssl rand -base64 33
```
## Apply settings
Restart Conduit.
Restart Conduit.