docs: Use mdbook for docs

.gitignore

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

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

.gitlab/route-map.yml

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

Cargo.toml

@@ -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 = """\

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

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

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)

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

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
 

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)

docs/deploy/binary.md

@@ -1,22 +1,25 @@
-# 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.
+
+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 (Most servers and computers) | [Download][x84_64-musl-master] | [Download][x84_64-musl-next] |
+| -------------------- | ------------------------------ | ---------------------------- |
+| x84_64 / amd64       | [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]  |
+| 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
@@ -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).

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
+
+\
+
+<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.
 

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

docs/turn.md

@@ -1,12 +1,14 @@
 # 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
 
-```
+```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.