From 70b6890eddb23b3f599dd0639559b00774df38e2 Mon Sep 17 00:00:00 2001 From: Jonas Zohren Date: Sun, 6 Feb 2022 17:48:06 +0100 Subject: [PATCH] docs: Use mdbook for docs --- .gitignore | 2 + .gitlab-ci.yml | 70 +++++++++- .gitlab/route-map.yml | 3 + Cargo.toml | 2 +- README.md | 65 ++++----- book.toml | 16 +++ docs/SUMMARY.md | 10 ++ docs/_getting_help.md | 7 + APPSERVICES.md => docs/appservices.md | 4 +- docs/deploy/_index.md | 17 +++ DEPLOY.md => docs/deploy/binary.md | 154 ++++++++++------------ docker/README.md => docs/deploy/docker.md | 93 ++++++++----- docs/deploy/packages.md | 45 +++++++ TURN.md => docs/turn.md | 16 ++- 14 files changed, 342 insertions(+), 162 deletions(-) create mode 100644 .gitlab/route-map.yml create mode 100644 book.toml create mode 100644 docs/SUMMARY.md create mode 100644 docs/_getting_help.md rename APPSERVICES.md => docs/appservices.md (87%) create mode 100644 docs/deploy/_index.md rename DEPLOY.md => docs/deploy/binary.md (53%) rename docker/README.md => docs/deploy/docker.md (65%) create mode 100644 docs/deploy/packages.md rename TURN.md => docs/turn.md (63%) diff --git a/.gitignore b/.gitignore index f5e9505b..2d65e3cf 100644 --- a/.gitignore +++ b/.gitignore @@ -59,6 +59,8 @@ $RECYCLE.BIN/ # Conduit conduit.toml conduit.db +public/ +index.html # Etc. **/*.rs.bk diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 380332b1..f56d2c3c 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -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: diff --git a/.gitlab/route-map.yml b/.gitlab/route-map.yml new file mode 100644 index 00000000..cf31bd18 --- /dev/null +++ b/.gitlab/route-map.yml @@ -0,0 +1,3 @@ +# Docs: Map markdown to html files +- source: /docs/(.+)\.md/ + public: '\1.html' diff --git a/Cargo.toml b/Cargo.toml index 64b7a233..90f42ad8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -114,7 +114,7 @@ path = "src/lib.rs" [package.metadata.deb] name = "matrix-conduit" maintainer = "Paul van Tilburg " -copyright = "2020, Timo Kösters " +copyright = "2022, Timo Kösters " license-file = ["LICENSE", "3"] depends = "$auto, ca-certificates" extended-description = """\ diff --git a/README.md b/README.md index 730b2512..da5677c5 100644 --- a/README.md +++ b/README.md @@ -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 + +
+What is the goal? 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? +
+ +
+Can I try it out? Yes! You can test our Conduit instance by opening a Matrix client ( 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? +
+ +
+What is the current status? 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? +
-- 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: \ -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)) diff --git a/book.toml b/book.toml new file mode 100644 index 00000000..259c125f --- /dev/null +++ b/book.toml @@ -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 diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 00000000..edccb13f --- /dev/null +++ b/docs/SUMMARY.md @@ -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) diff --git a/docs/_getting_help.md b/docs/_getting_help.md new file mode 100644 index 00000000..8166fba9 --- /dev/null +++ b/docs/_getting_help.md @@ -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). diff --git a/APPSERVICES.md b/docs/appservices.md similarity index 87% rename from APPSERVICES.md rename to docs/appservices.md index 8ca015a0..a9e39c6f 100644 --- a/APPSERVICES.md +++ b/docs/appservices.md @@ -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 diff --git a/docs/deploy/_index.md b/docs/deploy/_index.md new file mode 100644 index 00000000..db393cc4 --- /dev/null +++ b/docs/deploy/_index.md @@ -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) diff --git a/DEPLOY.md b/docs/deploy/binary.md similarity index 53% rename from DEPLOY.md rename to docs/deploy/binary.md index a711cc90..2a2f93b0 100644 --- a/DEPLOY.md +++ b/docs/deploy/binary.md @@ -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 -$ sudo chmod +x /usr/local/bin/matrix-conduit +sudo wget -O /usr/local/bin/matrix-conduit +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). +
+Cross-Compiling to different architectures + +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` + +
## 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 , 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). diff --git a/docker/README.md b/docs/deploy/docker.md similarity index 65% rename from docker/README.md rename to docs/deploy/docker.md index c980adcc..2f621514 100644 --- a/docker/README.md +++ b/docs/deploy/docker.md @@ -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 + +\ + +
+Want to build your own image? + +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`. + +
### 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. diff --git a/docs/deploy/packages.md b/docs/deploy/packages.md new file mode 100644 index 00000000..b93fafac --- /dev/null +++ b/docs/deploy/packages.md @@ -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 +``` \ No newline at end of file diff --git a/TURN.md b/docs/turn.md similarity index 63% rename from TURN.md rename to docs/turn.md index 63c1e99f..26866801 100644 --- a/TURN.md +++ b/docs/turn.md @@ -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. \ No newline at end of file +Restart Conduit.