Browse Source
Draft: Documentation overhaul for 1.0 See merge request famedly/conduit!159merge-requests/159/merge
Jonas Zohren
4 years ago
21 changed files with 249 additions and 14 deletions
@ -1,11 +0,0 @@ |
|||||||
Install docker: |
|
||||||
|
|
||||||
``` |
|
||||||
$ sudo apt install docker |
|
||||||
$ sudo usermod -aG docker $USER |
|
||||||
$ exec sudo su -l $USER |
|
||||||
$ sudo systemctl start docker |
|
||||||
$ cargo install cross |
|
||||||
$ cross build --release --target armv7-unknown-linux-musleabihf |
|
||||||
``` |
|
||||||
The cross-compiled binary is at target/armv7-unknown-linux-musleabihf/release/conduit |
|
||||||
@ -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 |
||||||
@ -0,0 +1,16 @@ |
|||||||
|
# Summary |
||||||
|
|
||||||
|
[Home](index.md) |
||||||
|
|
||||||
|
- [Installation](installation.md) |
||||||
|
- [Prerequisites](installation/prerequisites.md) |
||||||
|
- [From Binaries](installation/manual.md) |
||||||
|
- [From Packages](installation/packages.md) |
||||||
|
- [With Docker](installation/docker.md) |
||||||
|
- [Configuration](configuration.md) |
||||||
|
- [Config options](configuration/configuration.md) |
||||||
|
- [Appservices](configuration/appservices.md) |
||||||
|
- [Contribute](contribute.md) |
||||||
|
- [Basics](development/basics.md) |
||||||
|
- [Cross compilation](development/cross-compilation.md) |
||||||
|
- [Tests & CI](development/tests-ci.md) |
||||||
@ -0,0 +1,34 @@ |
|||||||
|
# Configuring Conduit |
||||||
|
|
||||||
|
Conduit can be configured via a config file (conventionally called Conduit.toml) or environment variables. If a config |
||||||
|
file exists and environment variables are set, environment variables overwrite config options. |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
| Key in Conduit.toml | Environment variable | Default value | Description | |
||||||
|
|---------------------|-------------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
||||||
|
| `server_name` | `CONDUIT_SERVER_NAME` | | 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 (server-server) OR you can create /.well-known files to redirect requests. See [Client-Server specs](https://matrix.org/docs/spec/client_server/latest#get-well-known-matrix-client) and [Server-Server specs](https://matrix.org/docs/spec/server_server/r0.1.4#get-well-known-matrix-server) for more information. | |
||||||
|
| `database_path` | `CONDUIT_DATABASE_PATH` | `/var/lib/conduit/` | A directory Conduit where Conduit stores its database and media files. This directory must exist and be writable before Conduit is started. | |
||||||
|
| `port` | `CONDUIT_PORT` | `6167` | 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. | |
||||||
|
|
||||||
|
## Optional config options |
||||||
|
|
||||||
|
| Key in Conduit.toml | Environment variable | Default value | Description | |
||||||
|
|---------------------------|-----------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
||||||
|
| `max_request_size` | `CONDUIT_MAX_REQUEST_SIZE` | `20_000_000` | The maximum size in bytes for uploads (files sent from users on this Conduit server). Uploads will be stored in the database path, so make sure that it has sufficient free space. | |
||||||
|
| `allow_registration` | `CONDUIT_ALLOW_REGISTRATION` | `true` | Are new users allowed to register accounts on their own? Possible values: `true`, `false`. | |
||||||
|
| `allow_encryption` | `CONDUIT_ALLOW_ENCRYPTION` | `true` | Controls whether encrypted rooms can be created or not. Possible values: `true`, `false`. | |
||||||
|
| `allow_federation` | `CONDUIT_ALLOW_FEDERATION` | `false` | Federation enables users on your Conduit server to talk to other Matrix users on different Matrix servers. If federation is turned off, only users on your Conduit server can talk to each other. Possible values: `true`, `false`. | |
||||||
|
| `allow_jaeger` | `CONDUIT_ALLOW_JAEGER` | `false` | Enable jaeger to support monitoring and troubleshooting through jaeger. Possible values: `true`, `false`. | |
||||||
|
| `trusted_servers` | `CONDUIT_TRUSTED_SERVERS` | `[]` | List of servers, which Conduit trusts enough to ask them for public keys of other, newly found servers. E.g. to trust the matrix.org server, set this value to `["matrix.org"]`. | |
||||||
|
| `max_concurrent_requests` | `CONDUIT_MAX_CONCURRENT_REQUESTS` | `100` | How many requests Conduit sends to other servers at the same time. | |
||||||
|
| `log` | `CONDUIT_LOG` | `info,state_res=warn,rocket=off,_=off,sled=off` | Configures which kind of messages Conduit logs. | |
||||||
|
| `workers` | `CONDUIT_WORKERS` | cpu core count * 2 | How many worker processes are used. | |
||||||
|
| `address` | `CONDUIT_ADDRESS` | `127.0.0.1` | 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. | |
||||||
|
| `db_cache_capacity_mb` | `CONDUIT_DB_CACHE_CAPACITY_MB` | `200` | The total amount of memory that the database will use. (this needs clearification: In RAM or on disk and for what exactly?) | |
||||||
@ -0,0 +1,13 @@ |
|||||||
|
# Cross compilation |
||||||
|
|
||||||
|
Install docker: |
||||||
|
|
||||||
|
```bash |
||||||
|
sudo apt install docker |
||||||
|
sudo usermod -aG docker $USER |
||||||
|
exec sudo su -l $USER |
||||||
|
sudo systemctl start docker |
||||||
|
cargo install cross |
||||||
|
cross build --release --target armv7-unknown-linux-musleabihf |
||||||
|
``` |
||||||
|
The cross-compiled binary is at target/armv7-unknown-linux-musleabihf/release/conduit |
||||||
@ -0,0 +1,52 @@ |
|||||||
|
# Conduit |
||||||
|
|
||||||
|
Conduit is a simple, fast and reliable chat server for the [Matrix] protocol written in [Rust]. |
||||||
|
|
||||||
|
----- |
||||||
|
> Note: This project is work-in-progress. Do *not* rely on it yet. |
||||||
|
|
||||||
|
## What is Matrix? |
||||||
|
|
||||||
|
[Matrix] is an open network for secure and decentralized |
||||||
|
communication. It allows you to chat with friends even if they are using |
||||||
|
another servers and client. You can even use bridges to communicate with users |
||||||
|
outside of Matrix, like a community on Discord or your family on Hangouts. |
||||||
|
|
||||||
|
## Why Conduit? |
||||||
|
|
||||||
|
Conduit is an open-source server implementation of the [Matrix |
||||||
|
Specification] with a focus on easy setup and low |
||||||
|
system requirements, making it very easy to set up. |
||||||
|
|
||||||
|
Other server implementations try to be extremely scalable, which makes sense if |
||||||
|
the goal is to support millions of users on a single instance, but makes |
||||||
|
smaller deployments a lot more inefficient. Conduit tries to keep it simple but |
||||||
|
takes full advantage of that, for example by using an in-memory database for |
||||||
|
[huge performance gains](https://github.com/timokoesters/romeo-and-juliet-benchmark). |
||||||
|
|
||||||
|
The future for Conduit in peer-to-peer Matrix (every client contains a server) |
||||||
|
is also bright. |
||||||
|
|
||||||
|
Conduit tries to be reliable by using the Rust programming language and paying |
||||||
|
close attention to error handling to make sure that evil clients, misbehaving |
||||||
|
servers or even a partially broken database will not cause the whole server to |
||||||
|
stop working. |
||||||
|
|
||||||
|
## Chat with us! |
||||||
|
|
||||||
|
We have a room on Matrix: [#conduit:matrix.org](https://matrix.to/#/#conduit:matrix.org) |
||||||
|
|
||||||
|
You can also contact us using: |
||||||
|
- Matrix: [@timo:koesters.xyz](https://matrix.to/#/@timo:koesters.xyz) |
||||||
|
- Email: [conduit@koesters.xyz](mailto:conduit@koesters.xyz) |
||||||
|
|
||||||
|
|
||||||
|
## Donate |
||||||
|
|
||||||
|
Liberapay: <https://liberapay.com/timokoesters/>\ |
||||||
|
Bitcoin: `bc1qnnykf986tw49ur7wx9rpw2tevpsztvar5x8w4n` |
||||||
|
|
||||||
|
|
||||||
|
[Matrix]: https://matrix.org/ |
||||||
|
[Rust]: https://rust-lang.org |
||||||
|
[Matrix Specification]: https://matrix.org/docs/spec |
||||||
@ -0,0 +1,12 @@ |
|||||||
|
# Distribution packages |
||||||
|
|
||||||
|
## Debian / Ubuntu |
||||||
|
|
||||||
|
[@paul:luon.net](https://matrix.to/#/@paul:luon.net) plans to package Conduit for Debian as soon as it reaches 1.0. |
||||||
|
Until it is available in the official repos, you can install the development version of it manually: |
||||||
|
|
||||||
|
```bash |
||||||
|
sudo apt-get install ca-certificates |
||||||
|
wget --https-only -O /tmp/conduit.deb https://gitlab.com/famedly/conduit/-/jobs/artifacts/master/raw/conduit-x86_64-unknown-linux-gnu.deb?job=build:cargo-deb:x86_64-unknown-linux-gnu |
||||||
|
sudo dpkg -i /tmp/conduit.deb |
||||||
|
``` |
||||||
@ -0,0 +1,31 @@ |
|||||||
|
# Prerequisites for running Conduit |
||||||
|
|
||||||
|
You'll need: |
||||||
|
|
||||||
|
- A domain. Commonly cost about $10/year. |
||||||
|
- A Linux server with a stable internet connection, at least 500 MB of RAM and some disk space for messages and |
||||||
|
attachments. Commonly start at $5/month. |
||||||
|
- Some basic knowledge about using a shell, SSH and configuring and protecting a server. |
||||||
|
|
||||||
|
|
||||||
|
## A word of caution: |
||||||
|
|
||||||
|
Don't underestimate the toll of administrating your own server. |
||||||
|
Conduit can't protect your conversations if your server gets compromised or deleted. |
||||||
|
|
||||||
|
Make sure that you got: |
||||||
|
|
||||||
|
- Automatic security updates |
||||||
|
- On Ubuntu/Debian: Set up unattended-upgrades |
||||||
|
- On RHEL/CentOS: Have a look at yum-cron |
||||||
|
- A firewall blocking all but the needed incoming ports |
||||||
|
- ufw is an easy interface for the linux firewall |
||||||
|
- Protection against automatic attacks |
||||||
|
- fail2ban scans logs and bans IPs which try to brute force their way into your server. |
||||||
|
- Disable ssh login for root and switch from password to key based authentication. |
||||||
|
- Automated backups |
||||||
|
- Most VPS hosting companies offer whole server backups for a small fee. |
||||||
|
- Or run your own backup with something like borg. |
||||||
|
- A way to get notified if your disk fills up. |
||||||
|
- If you send too much cat videos to your friends, Conduit might at some point become unable to |
||||||
|
store any important messages. |
||||||
@ -0,0 +1,40 @@ |
|||||||
|
# About Matrix Homeservers |
||||||
|
|
||||||
|
Matrix homeservers manage its users chats. Every Matrix username includes the homserver it belongs to: |
||||||
|
`@alice:matrix.org` means that the `matrix.org` homeserver hosts a user called `@alice`. |
||||||
|
Every time someone chats with Alice, the `matrix.org` homeserver stores these messages. |
||||||
|
When `@alice:matrix.org` talks with `@adelaide:matrix.org`, that's easy. Both users use the same server. |
||||||
|
|
||||||
|
But how can `@bob:vector.tld`, who uses the `vector.tld` homeserver, exchange messages with `@alice:matrix.org`? |
||||||
|
This is where it get's a bit more complicated. |
||||||
|
|
||||||
|
## Matrix Homeserver discovery |
||||||
|
|
||||||
|
The Matrix specification specifies multiple ways how servers can discover and then talk to each other. |
||||||
|
Let's look at the most common one: |
||||||
|
|
||||||
|
### .well-known files |
||||||
|
|
||||||
|
At first, the only information a server has about a user (e.g. `@bob:vector.tld`) is its homeserver name: `vector.tld`. |
||||||
|
It then makes a HTTP GET request to `https://vector.tld/.well-known/matrix/server`. |
||||||
|
In the ideal case, this file contains a content like this: |
||||||
|
|
||||||
|
```json |
||||||
|
{ |
||||||
|
"m.server": "matrix.vector.tld:443" |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
This translates to: The matrix homeserver software for users with a username ending on `vector.tld` |
||||||
|
can be found at the address `matrix.vector.tld` at port 443 (which is the common port for HTTPS). |
||||||
|
|
||||||
|
The homeserver on it's quest to find `@bob:vector.tld` now contacts `matrix.vector.tld:443` and is then |
||||||
|
able to exchange chat messages with it. |
||||||
|
|
||||||
|
|
||||||
|
### Why so complicated? |
||||||
|
|
||||||
|
Organizations often don't want to run their Matrix server on the same machine that hosts their website, |
||||||
|
but `@foo:matrix.evil.corp` usernames are ugly and everyone wants to be `@foo:evil.corp`. |
||||||
|
|
||||||
|
To solve that problem, Matrix implements this extra step via a .well-known file or a DNS entry. |
||||||
Loading…
Reference in new issue