Move some documentation to docs/ and start overhaul

.gitlab-ci.yml

@@ -3,6 +3,7 @@ stages:
   - build docker image
   - test
   - upload artifacts
+  - publish
 
 variables:
   GIT_SUBMODULE_STRATEGY: recursive
@@ -295,4 +296,18 @@ publish:package:
     - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file conduit-x86_64-unknown-linux-musl "${BASE_URL}/conduit-x86_64-unknown-linux-musl"'
     - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file conduit-x86_64-unknown-linux-gnu.deb "${BASE_URL}/conduit-x86_64-unknown-linux-gnu.deb"'
 
-    
+
+pages:
+  stage: "publish"
+  image:
+    name: "squidfunk/mkdocs-material"
+    entrypoint: [""]
+  tags: ["docker"]
+  needs: []
+  rules:
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+  script:
+    - "mkdocs build --site-dir public"
+  artifacts:
+    paths:
+      - "public"

CROSS_COMPILE.md

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

DEPLOY.md

@@ -148,7 +148,7 @@ This depends on whether you use Apache, Nginx or another web server.
 
 Create `/etc/apache2/sites-enabled/050-conduit.conf` and copy-and-paste this:
 
-```
+```apache
 Listen 8448
 
 <VirtualHost *:443 *:8448>
@@ -177,7 +177,7 @@ $ sudo systemctl reload apache2
 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;

README.md

@@ -52,7 +52,7 @@ Check out the [Conduit 1.0 Release Milestone](https://gitlab.com/famedly/conduit
 Download or compile a Conduit binary, set up the config and call it from somewhere like a systemd script. [Read
 more](DEPLOY.md)
 
-If you want to connect an Appservice to Conduit, take a look at the [Appservice Guide](APPSERVICES.md).
+If you want to connect an Appservice to Conduit, take a look at the [Appservice Guide](docs/configuration/appservices.md).
 
 ##### Deploy using a Debian package
 

docs/configuration/appservices.md

@@ -7,6 +7,7 @@ If you run into any problems while setting up an Appservice, write an email to `
 ## Tested appservices
 
 Here are some appservices we tested and that work with Conduit:
+
 - matrix-appservice-discord
 - mautrix-hangouts
 - mautrix-telegram
@@ -38,6 +39,7 @@ the room like this:
     ```
 
 You can confirm it worked by sending a message like this:
+
 `@conduit:your.server.name: list_appservices`
 
 The @conduit bot should answer with `Appservices (1): your-bridge`

docs/configuration/conduit.toml.md

@@ -0,0 +1,2 @@
+# Configuring Conduit
+

docs/development/cross-compilation.md

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

docs/index.md

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

docs/installation/packages.md

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

docs/installation/prerequisites.md

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

docs/matrix-homeservers.md

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

mkdocs.yml

@@ -0,0 +1,20 @@
+site_name: Conduit Docs
+site_description: Conduit is a simple, fast and reliable chat server for the Matrix protocol
+theme:
+  name: material
+repo_url: https://gitlab.com/famedly/conduit
+nav:
+  - Home: index.md
+  - Installation:
+      - Prerequisites: installation/prerequisites.md
+      - Distribution Packages: installation/packages.md
+      - Manual: installation/manual.md
+      - Docker: installation/docker.md
+  - Configuration:
+      - Conduit.toml: configuration/conduit.toml.md
+      - Appservices: configuration/appservices.md
+  - Development:
+      - Basics: development/basics.md
+      - Cross compilation: development/cross-compilation.md
+      - Tests & CI: development/tests-ci.md
+