Start working on dedicated docs, WIP

.gitignore

@@ -60,6 +60,7 @@ $RECYCLE.BIN/
 Rocket.toml
 conduit.toml
 conduit.db
+public/
 
 # Etc.
 **/*.rs.bk

.gitlab-ci.yml

@@ -299,6 +299,25 @@ 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"'
 
+pages:
+  stage: deploy
+  image: rust
+  variables:
+    CARGO_HOME: $CI_PROJECT_DIR/cargo
+  before_script:
+    - export PATH="$PATH:$CARGO_HOME/bin"
+    - mdbook --version || cargo install mdbook
+  script:
+    - mdbook build -d public
+  rules:
+    - if: '$CI_COMMIT_REF_NAME == "master"'
+  artifacts:
+    paths:
+      - public
+  cache:
+    paths:
+      - $CARGO_HOME/bin
+
 # Avoid duplicate pipelines
 # See: https://docs.gitlab.com/ee/ci/yaml/workflow.html#switch-between-branch-pipelines-and-merge-request-pipelines
 workflow:

book.toml

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

docs/SUMMARY.md

@@ -0,0 +1,10 @@
+# Conduit Matrix Server
+
+[Introduction](index.md)
+
+- [Setup](setup.md)
+  - [Domain](setup/domain.md)
+  - [Installation](installation.md)
+    - [Binary](setup/installation/binary.md)
+    - [Docker](setup/installation/docker.md)
+  - [Configuration](setup/configuration-options.md)

docs/index.md

@@ -0,0 +1,29 @@
+## What is Conduit?
+
+**Conduit** is an efficient Matrix homeserver written in [Rust](https://rust-lang.org), 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.
+
+## Setup your own Conduit
+
+1. [Choose your domain](setup/domain.md)
+2. Choose your deployment type
+   - Binary
+   - Docker
+3. Configuration your Conduit
+   - Environment variables
+   - Config file
+
+## Donate
+
+- Liberapay: <https://liberapay.com/timokoesters/>\
+- Bitcoin: `bc1qnnykf986tw49ur7wx9rpw2tevpsztvar5x8w4n`
+
+## Contribute
+
+See [the git repository](https://gitlab.com/famedly/conduit/) for more info on how to work on Conduit's code.
+
+## Licenses
+
+Conduit's code and documentation is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+The [lightning bolt logo](https://github.com/mozilla/fxemoji/blob/gh-pages/svgs/nature/u26A1-bolt.svg) is licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://github.com/mozilla/fxemoji/blob/gh-pages/LICENSE.md)

docs/installation.md

@@ -0,0 +1 @@
+# Installation

docs/setup.md

@@ -0,0 +1 @@
+# Setup

docs/setup/configuration-options.md

@@ -0,0 +1,226 @@
+# Configuring Conduit
+
+Conduit can be configured via a config file (conventionally called Conduit.toml) or environment variables.
+If a config option is set in both the config file and as an environment variable, the environment variable takes precedence.
+
+You absolutely need to set the environment variable `CONDUIT_CONFIG_FILE` to either point to a config file (
+e.g. `CONDUIT_CONFIG_FILE=/etc/conduit/Conduit.toml`) or to an empty string (`CONDUIT_CONFIG_FILE=''`) if you want to
+configure Conduit with just environment variables.
+
+---
+
+## Mandatory config options
+
+Mandatory variables must be configured in order for Conduit to run properly.
+
+### Server Name
+
+- Config file key: `server_name`
+- Envirnoment variable: `CONDUIT_SERVER_NAME`
+- Default value: _None, you will need to choose your own._
+
+The server_name is the name of this server. It is used as a suffix for user and room ids. Example: If you set it
+to `conduit.rs`, your usernames will look like `@somebody:conduit.rs`.
+
+The Conduit server needs to be reachable at https://your.server.name/ on port 443 (client-server) and 8448 (
+server-server) OR you can create /.well-known files to redirect requests. See
+the [Client-Server specs](https://matrix.org/docs/spec/client_server/latest#get-well-known-matrix-client) and
+the [Server-Server specs](https://matrix.org/docs/spec/server_server/r0.1.4#get-well-known-matrix-server) for more
+information.
+
+### Database Path
+
+- Config file key: `database_path`
+- Envirnoment variable: `CONDUIT_DATABASE_PATH`
+- Default value: _None, but many people like to use `/var/lib/conduit/`_.
+
+A **directory** where Conduit stores its database and media files. This directory must exist, have enough free space and
+be readable and writable by the user Conduit is running as.
+
+What does _enough free space_ mean? It heavily on the amount of messages your Conduit server will see and the amount and
+size of media files users on your Conduit server send. As a rule of thumb, you should have at least 10 GB of free space
+left. You should be comfortable for quite some time with 50 GB.
+
+### Port
+
+- Config file key: `port`
+- Environment variable: `CONDUIT_PORT`
+- Default value: _None, but many people like to use `6167`_.
+
+The TCP port Conduit will listen on for connections. The port needs to be free (no other program is listeing on it).
+
+Conduit does currently (2021-12) not offer HTTPS by itself. Only unencrypted HTTP requests will be accepted on this
+port. Unless you know what you are doing, this port should not be exposed to the internet. Instead, use a reverse proxy
+capable of doing TLS to offer your Conduit server to the internet via HTTPS.
+
+---
+
+## Optional configuration options
+
+These config options come with defaults and don't need to be configured for Conduit to run. That said, you should still
+check them to make sure that your Conduit server behaves like you want it to do.
+
+### Maximum request size
+
+- Config file key: `max_request_size`
+- Environment variable: `CONDUIT_MAX_REQUEST_SIZE`
+- Default value: `20_000_000` (~= 20 MB)
+
+The maximum size in bytes for incoming requests to Conduit. You can use underscores to improve readability.
+
+This will effectively limit the size for images, videos and other files users on your Conduit server can send.
+
+### Allow Registration?
+
+- Config file key: `allow_registration`
+- Environment variable: `CONDUIT_ALLOW_REGISTRATION`
+- Default value: `true`
+- Possible values: `true`, `false`
+
+It this is set to `false`, no new users can register accounts on your Conduit server. Already registered users will not
+be affected from this setting and can continue to user your server.
+
+The first user to ever register on your Conduit server will be considered the admin account and is automatically invited
+into the admin room.
+
+### Allow Encryption?
+
+- Config file key: `allow_encryption`
+- Environment variable: `CONDUIT_ALLOW_ENCRYPTION`
+- Default value: `true`
+- Possible values: `true`, `false`
+
+If this is set to `false`, Conduit disables the ability for users to create encrypted chats. Existing encrypted chats
+may continue to work.
+
+### Allow federation?
+
+- Config file key: `allow_federation`
+- Environment variable: `CONDUIT_ALLOW_FEDERATION`
+- Default value: `false`
+- Possible values: `true`, `false`
+
+Federation means that users from different Matrix servers can chat with each other. E.g. `@mathew:matrix.org` can chat
+with `@timo:conduit.rs`.
+
+If this option is set to `false`, users on your Conduit server can only talk with other users on your Conduit server.
+
+Federation with other servers needs to happen over HTTPS, so make sure you have set up a reverse proxy.
+
+You can use the [Federation Tester](https://federationtester.matrix.org/) to test your federation ability.
+
+### Jaeger Tracing
+
+- Config file key: `allow_jaeger`
+- Environment variable: `CONDUIT_ALLOW_JAEGER`
+- Default value: `false`
+- Possible values: `true`, `false`
+
+Enable Jaeger to support monitoring and troubleshooting through Jaeger.
+
+If you don't know what Jaeger is, you can safely leave this set to `false`.
+
+### Trusted servers
+
+- Config file key: `trusted_servers`
+- Environment variable: `CONDUIT_TRUSTED_SERVERS`
+- Default value: `[]`
+- Possible values: JSON-Array of server domains, e.g. `["matrix.org"]` or `["matrix.org", "conduit.rs"]`.
+
+Matrix servers have so-called "server keys", which authenticate messages from their users. Because your Conduit server
+might not know the server keys from every server it encounters, it can ask a _trusted server_ for them. This speeds
+things up for rooms with people from a lot of different servers.
+
+You should only set this to include trustworthy servers. Most people consider `["matrix.org"]` to bea good default.
+
+Only relevant if you have federation enabled.
+
+### Limit amount of concurrent requests
+
+- Config file key: `max_concurrent_requests`
+- Environment variable: `CONDUIT_MAX_CONCURRENT_REQUESTS`
+- Default value: `100`
+- Suggested values: `1` - `1000` (u16)
+
+How many requests Conduit can make at the same time. This affects federation with other Matrix servers, push
+notifications and app_services.
+
+// TODO Timo: When does it make sense to change this?
+
+### Configure logging
+
+- Config file key: `log`
+- Environment variable: `CONDUIT_LOG`
+- Default value: `info,state_res=warn,rocket=off,_=off,sled=off`
+
+Configures which kind of messages Conduit logs.
+
+> // TODO: Better and more thorough explanation
+
+### Worker threads
+
+- Config file key: `workers`
+- Environment variable: `CONDUIT_WORKERS`
+- Default value: cpu core count \* 2
+- Possible values: // TODO
+
+> // TODO: Which thing exactly threads? What not?
+
+### Listening address
+
+- Config file key: `address`
+- Environment variable: `CONDUIT_ADDRESS`
+- Default value: `127.0.0.1`
+- Possible values: Valid IP addresses.
+
+Which IP address conduit is listening on. 127.0.0.1 means that Conduit can only be accessed from the same server or
+through a reverse proxy on that server. If you want it to be accessible from any network interface (which you should
+not, because other matrix servers should talk to your Conduit via a reverse proxy and not directly), you can set it
+to `0.0.0.0`.
+
+### Database cache capacity
+
+- Config file key: `db_cache_capacity_mb`
+- Environment variable: `CONDUIT_DB_CACHE_CAPACITY_MB`
+- Default value: `200`
+- Possible values: `true`, `false`
+
+The total amount of memory (RAM) that the database cache will be able to use.
+
+> // TODO: this needs clearification: In RAM or on disk and for what exactly?
+
+### PDU cache capacity
+
+- Config file key: `pdu_cache_capacity`
+- Environment variable: `CONDUIT_PDU_CACHE_CAPACITY`
+- Default value: `100_000`
+- Suggested values: `1_000` - `1_000_000` (u32)
+
+The total capacity (read: number of items) the pdu cache can hold in memory. Setting this to a lower number may slow
+Conduit down, as it must fetch more data from the database. Increasing it will mean that Conduit will start to use more
+memory as the cache slowly fills up.
+
+### SQLite WAL clean interval
+
+- Config file key: `sqlite_wal_clean_second_interval`
+- Environment variable: `CONDUIT_SQLITE_WAL_CLEAN_SECOND_INTERVAL`
+- Default value: `60` (every 60 seconds)
+- Suggested values: `1` - `3600` (u32)
+
+How often the WAL file should be cleaned up. The WAL file will be written to until cleaned up, after which it restarts
+writing from the beginning.
+
+The file's size will correspond to how long it could write to it in one go. (e.g. if conduit writes 100MB of data to the
+database inbetween that period, the file will grow to 100MB). You can read more about that in
+the [SQLite Docs](https://www.sqlite.org/draft/wal.html).
+
+Reducing this down too much can offset the benefits of using a WAL at all. However, having this too high can result in a
+large WAL file.
+
+Only relevant when using SQLite as the database.
+
+### Still undocumented config options
+
+- `tracing_flame`
+- `proxy`
+- `jwt_secret`

docs/setup/domain.md

@@ -0,0 +1,82 @@
+# Domains?
+
+## How Matrix (commonly) works
+
+If you think about the way Matrix works, you will probably have this rough idea in your head:
+
+![Sketch of two users, "@alice:a.com" and "@bob:b.com", each connected via an arrow to one server, "a.com" and "b.com". There is a connection arrow between those servers.](../matrix-rough-overview.svg)
+
+So as @alice:a.com you are connected to your Matrix Homeserver which is a.com and if you chat with @bob:b.com, your Homeserver talks with Bob's Homeserver, b.com.
+
+But how does your Matrix App know how to talk with your Homeserver, and how does your Homeserver know how to talk with other Homeservers?
+
+## How your Matrix Client finds your Homeserver
+
+1. You open your Matrix Client for the first time and type in your homeserver url: `example.com`.
+2. Your Matrix client sends an http(s) request to `example.com/.well-known/matrix/client`.
+3. The Webserver answers with a file like this:
+
+```json
+{
+  "m.homeserver": {
+    "base_url": "https://matrix.example.com"
+  }
+}
+```
+
+4. Your Matrix client connects to `https://matrix.example.com` and checks if it is a Matrix home server.
+5. You can register and log in as `@alice:example.com`
+
+So the actual homeserver can have a different url (`matrix.example.com`) than the domain in your username (`example.com`). So the sketch from above get's a bit more complicated:
+
+![Sketch of a user which as a first arrow going to a box labeled "Webserver A a.com" and a second arrow going to another box labeled "Homeserver A matrix.a.com"](../matrix-client-connection.svg)
+
+## How your Homeserver finds other Homeservers
+
+Now you want to message `@bob:b.com`. How does your Homeserver know how to talk to bob?
+
+1. You send a message in a chat with `@bob:b.com`.
+2. Your Homeserver sends an HTTP request to `b.com/.well-known/matrix/server`.
+3. The webserver of `b.com` answers with a file like this:
+
+```json
+{
+  "m.server": "matrix.b.com:443"
+}
+```
+
+4. Your homeserver connects to `https://matrix.b.com` on port 443 (the default port for HTTPS) and delivers your message to `@bob:b.com`.
+
+Our diagram got even more complicated:
+
+![](../matrix-with-homeserver-discovery.svg)
+
+## Does this need to be this complicated?
+
+The Matrix protocol is rather flexible to allow for big Homeservers with millions of users. This split between your domain (`a.com`) and the actual Homeserver url (`matrix.a.com`) allows to run a Website for `a.com` on one physical server and the Matrix Homeserver on another physical server and other fancy, but complicated magic.
+
+## How to choose a setup for your own Homeserver
+
+So what to do?
+
+You will probably have a fancy domain, let's call it `example.com`.
+Your users shall have names like `@chris:example.com` or `@danielle:example.com`.
+
+In our guides, we assume you control the DNS settings for your domain and are able to setup a subdomain.
+We also assume that you have a Linux server with a public IP address with ports 443 (and maybe 80) opened up in your firewall and some free disk space.
+
+You should setup a reverse-proxying webserver like nginx, apache, traefik or caddy to
+
+- Serve `https://example.com/.well-known/matrix/client`
+- Serve `https://example.com/.well-known/matrix/server`
+- Proxy `https://matrix.example.com/` to Conduit
+
+(Again: Substitute example.com with your own, even better domain.)
+
+## Alright, let's get started!
+
+We documented a few routes to get to a working Conduit server. Choose which one you like:
+
+- The manual way (best tested)
+- Docker compose
+- Docker + Reverse proxy

docs/setup/installation/binary.md

@@ -0,0 +1,232 @@
+## Installing Conduit
+
+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.
+
+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        |
+| ------------------------------------------- | ------------------------------ |
+| x84_64 / amd64 (Most servers and computers) | [Download][x84_64-musl-master] |
+| armv6                                       | [Download][armv6-musl-master]  |
+| armv7 (e.g. Raspberry Pi by default)        | [Download][armv7-musl-master]  |
+| armv8 / aarch64                             | [Download][armv8-musl-master]  |
+
+[x84_64-musl-master]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-x86_64-unknown-linux-musl?job=build:release:cargo:x86_64-unknown-linux-musl
+[armv6-musl-master]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-arm-unknown-linux-musleabihf?job=build:release:cargo:arm-unknown-linux-musleabihf
+[armv7-musl-master]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-armv7-unknown-linux-musleabihf?job=build:release:cargo:armv7-unknown-linux-musleabihf
+[armv8-musl-master]: https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-aarch64-unknown-linux-musl?job=build:release:cargo:aarch64-unknown-linux-musl
+
+```bash
+$ sudo wget -O /usr/local/bin/matrix-conduit <url>
+$ sudo chmod +x /usr/local/bin/matrix-conduit
+```
+
+Alternatively, you may compile the binary yourself using
+
+```bash
+$ cargo build --release
+```
+
+Note that this currently requires Rust 1.50.
+
+If you want to cross compile Conduit to another architecture, read the [Cross-Compile Guide](CROSS_COMPILE.md).
+
+## Adding a Conduit user
+
+While Conduit can run as any user it is usually better to use dedicated users for different services. This also allows
+you to make sure that the file permissions are correctly set up.
+
+In Debian you can use this command to create a Conduit user:
+
+```bash
+sudo adduser --system conduit --no-create-home
+```
+
+## Setting up a systemd service
+
+Now we'll set up a systemd service for Conduit, so it's easy to start/stop Conduit and set it to autostart when your
+server reboots. Simply paste the default systemd service you can find below into
+`/etc/systemd/system/conduit.service`.
+
+```systemd
+[Unit]
+Description=Conduit Matrix Server
+After=network.target
+
+[Service]
+Environment="CONDUIT_CONFIG=/etc/matrix-conduit/conduit.toml"
+User=conduit
+Group=nogroup
+Restart=always
+ExecStart=/usr/local/bin/matrix-conduit
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Finally, run
+
+```bash
+$ sudo systemctl daemon-reload
+```
+
+## Creating the Conduit configuration file
+
+Now we need to create the Conduit's config file in `/etc/matrix-conduit/conduit.toml`. Paste this in **and take a moment
+to read it. You need to change at least the server name.**
+
+```toml
+[global]
+# The server_name is the name of this server. It is used as a suffix for user
+# and room ids. Examples: matrix.org, conduit.rs
+# The Conduit server needs to be reachable at https://your.server.name/ on port
+# 443 (client-server) and 8448 (federation) OR 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/conduit_db"
+
+# 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
+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
+
+# Disable encryption, so no new encrypted rooms can be created
+# Note: existing rooms will continue to work
+allow_encryption = true
+allow_federation = true
+
+trusted_servers = ["matrix.org"]
+
+#max_concurrent_requests = 100 # How many requests Conduit sends to other servers at the same time
+#workers = 4 # default: cpu core count * 2
+
+address = "127.0.0.1" # This makes sure Conduit can only be reached using the reverse proxy
+
+# The total amount of memory that the database will use.
+#db_cache_capacity_mb = 200
+```
+
+## Setting the correct file permissions
+
+As we are using a Conduit specific user we need to allow it to read the config. To do that you can run this command on
+Debian:
+
+```bash
+sudo chown -R conduit:nogroup /etc/matrix-conduit
+```
+
+If you use the default database path you also need to run this:
+
+```bash
+sudo mkdir -p /var/lib/matrix-conduit/conduit_db
+sudo chown -R conduit:nogroup /var/lib/matrix-conduit/conduit_db
+```
+
+## Setting up the Reverse Proxy
+
+This depends on whether you use Apache, Nginx or another web server.
+
+### Apache
+
+Create `/etc/apache2/sites-enabled/050-conduit.conf` and copy-and-paste this:
+
+```apache
+Listen 8448
+
+<VirtualHost *:443 *:8448>
+
+ServerName your.server.name # EDIT THIS
+
+AllowEncodedSlashes NoDecode
+ProxyPass /_matrix/ http://127.0.0.1:6167/_matrix/ nocanon
+ProxyPassReverse /_matrix/ http://127.0.0.1:6167/_matrix/
+
+</VirtualHost>
+```
+
+**You need to make some edits again.** When you are done, run
+
+```bash
+$ sudo systemctl reload apache2
+```
+
+### Nginx
+
+If you use Nginx and not Apache, add the following server section inside the http section of `/etc/nginx/nginx.conf`
+
+```nginx
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    listen 8448 ssl http2;
+    listen [::]:8448 ssl http2;
+    server_name your.server.name; # EDIT THIS
+    merge_slashes off;
+
+    location /_matrix/ {
+        proxy_pass http://127.0.0.1:6167$request_uri;
+        proxy_set_header Host $http_host;
+        proxy_buffering off;
+    }
+
+    ssl_certificate /etc/letsencrypt/live/your.server.name/fullchain.pem; # EDIT THIS
+    ssl_certificate_key /etc/letsencrypt/live/your.server.name/privkey.pem; # EDIT THIS
+    ssl_trusted_certificate /etc/letsencrypt/live/your.server.name/chain.pem; # EDIT THIS
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+}
+```
+
+**You need to make some edits again.** When you are done, run
+
+```bash
+$ sudo systemctl reload nginx
+```
+
+## SSL Certificate
+
+The easiest way to get an SSL certificate, if you don't have one already, is to install `certbot` and run this:
+
+```bash
+$ sudo certbot -d your.server.name
+```
+
+## You're done!
+
+Now you can start Conduit with:
+
+```bash
+$ sudo systemctl start conduit
+```
+
+Set it to start automatically when your system boots with:
+
+```bash
+$ sudo systemctl enable conduit
+```
+
+## How do I know it works?
+
+You can open <https://app.element.io>, enter your homeserver and try to register.
+
+You can also use these commands as a quick health check.
+
+```bash
+$ curl https://your.server.name/_matrix/client/versions
+$ curl https://your.server.name:8448/_matrix/client/versions
+```
+
+If you want to set up an appservice, take a look at the [Appservice Guide](APPSERVICES.md).

docs/setup/installation/docker.md

@@ -0,0 +1,121 @@
+# Deploy using Docker
+
+> **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.
+>
+> See the [Domain section](../domain.md) for more about this.
+
+## Standalone Docker image
+
+A typical way to start Conduit with Docker looks like this:
+
+```bash
+docker run \
+  --name "conduit" \
+  --detach \
+  --restart "unless-stopped" \
+  --env CONDUIT_CONFIG="" \
+  --env CONDUIT_SERVER_NAME="domain.tld" \
+  --env CONDUIT_ADDRESS="0.0.0.0" \
+  --env CONDUIT_ALLOW_REGISTRATION="true" \
+  --env CONDUIT_ALLOW_FEDERATION="true" \
+  --env CONDUIT_DATABASE_PATH="/srv/conduit/.local/share/conduit" \
+  --volume "/var/lib/conduit/:/srv/conduit/.local/share/conduit" \
+  --publish 6167:6167
+  matrixconduit/matrix-conduit:latest
+```
+
+<details>
+<summary>Explanation of the above command</summary>
+
+- `--name "conduit"` Create a container named "conduit"
+- `--detach` Detach from current terminal and run in the background
+- `--restart=unless-stopped` Restart if Conduit crashes or after reboots
+- `--env CONDUIT_CONFIG=""` Tell Conduit to only use environment variables (instead of a config file)
+- `--env CONDUIT_ADDRESS="0.0.0.0" ` Answer to requests from outside of the container...
+- `--publish 6167:6167` ... on port 6167
+
+</details>
+
+After a few seconds, your Conduit should be listening on port 6167.
+If you have Element Desktop installed on the same machine, try creating an account on the server `localhost:6167`.
+
+To check how your Conduit container is doing, you can use the commands `docker ps` and `docker logs conduit`.
+
+### Next steps
+
+For a functioning Matrix server which you can connect to from your phone and which federates with other Matrix servers, you still need to configure a reverse proxy to:
+
+- Forward https traffic as http to the Conduit container on port 6167
+- Serve .well-known files (see the [Domain section](../domain.md)) to tell Servers and clients where to find your Conduit
+- Optionally serve a Matrix Web Client like Element Web or FluffyChat Web.
+
+## Docker Compose
+
+We also provide a `docker-compose.yaml` file, which includes everything you need to run a complete Matrix Homeserver:
+
+- Conduit
+- The reverse proxy
+- Matrix Web Client
+
+To get started:
+
+1. Copy the `docker-compose.yaml` file to a new directory on your server.
+
+2. Edit it and adjust your configuration.
+
+3. Start it with
+
+```bash
+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 containerized app and services available through the web. With the
+two provided files, [`docker-compose.traefik.yml`](docker-compose.traefik.yml) and [`docker-compose.override.traefik.yml`](docker-compose.override.traefik.yml), it is
+equally easy to deploy and use Conduit, with a little caveat. If you already took a look at the files, then you should have seen the `well-known` service, and that is
+the little caveat. Traefik is simply a proxy and loadbalancer and is not able to serve any kind of content, but for Conduit to federate, we need to either expose ports
+`443` and `8448` or serve two endpoints `.well-known/matrix/client` and `.well-known/matrix/server`.
+
+With the service `well-known` we use a single `nginx` container that will serve those two files.
+
+So...step by step:
+
+1. Copy [`docker-compose.traefik.yml`](docker-compose.traefik.yml) and [`docker-compose.override.traefik.yml`](docker-compose.override.traefik.yml) from the repository and remove `.traefik` from the filenames.
+2. Open both files and modify/adjust them to your needs. Meaning, change the `CONDUIT_SERVER_NAME` and the volume host mappings according to your needs.
+3. 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.
+4. Uncomment the `element-web` service if you want to host your own Element Web Client and create a `element_config.json`.
+5. Create the files needed by the `well-known` service.
+
+   - `./nginx/matrix.conf` (relative to the compose file, you can change this, but then also need to change the volume mapping)
+
+     ```nginx
+     server {
+         server_name <SUBDOMAIN>.<DOMAIN>;
+         listen      80 default_server;
+
+         location /.well-known/matrix/ {
+             root /var/www;
+             default_type application/json;
+             add_header Access-Control-Allow-Origin *;
+         }
+     }
+     ```
+
+   - `./nginx/www/.well-known/matrix/client` (relative to the compose file, you can change this, but then also need to change the volume mapping)
+     ```json
+     {
+       "m.homeserver": {
+         "base_url": "https://<SUBDOMAIN>.<DOMAIN>"
+       }
+     }
+     ```
+   - `./nginx/www/.well-known/matrix/server` (relative to the compose file, you can change this, but then also need to change the volume mapping)
+     ```json
+     {
+       "m.server": "<SUBDOMAIN>.<DOMAIN>:443"
+     }
+     ```
+
+6. Run `docker-compose up -d`
+7. Connect to your homeserver with your preferred client and create a user. You should do this immediatly after starting Conduit, because the first created user is the admin.