Move some documentation to docs/ and start overhaul

docs/configuration/appservices.md

@@ -0,0 +1,50 @@
+# 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:matrix.org` or [open an issue on GitLab](https://gitlab.com/famedly/conduit/-/issues/new).
+
+## Tested appservices
+
+Here are some appservices we tested and that work with Conduit:
+
+- matrix-appservice-discord
+- mautrix-hangouts
+- mautrix-telegram
+
+## Set up the appservice
+
+Follow whatever instructions are given by the appservice. This usually includes
+downloading, changing its config (setting domain, homeserver url, port etc.)
+and later starting it.
+
+At some point the appservice guide should ask you to add a registration yaml
+file to the homeserver. In Synapse you would do this by adding the path to the
+homeserver.yaml, but in Conduit you can do this from within Matrix:
+
+First, go into the #admins room of your homeserver. The first person that
+registered on the homeserver automatically joins it. Then send a message into
+the room like this:
+
+    @conduit:your.server.name: register_appservice
+    ```
+    paste
+    the
+    contents
+    of
+    the
+    yaml
+    registration
+    here
+    ```
+
+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`
+
+Then you are done. Conduit will send messages to the appservices and the
+appservice can send requests to the homeserver. You don't need to restart
+Conduit, but if it doesn't work, restarting while the appservice is running
+could help.

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.