diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 6f9b78b3..faf225eb 100644 --- a/.gitlab-ci.yml +++ b/.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" diff --git a/CROSS_COMPILE.md b/CROSS_COMPILE.md deleted file mode 100644 index e38a6ad7..00000000 --- a/CROSS_COMPILE.md +++ /dev/null @@ -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 diff --git a/DEPLOY.md b/DEPLOY.md index 1010c0f4..f7214298 100644 --- a/DEPLOY.md +++ b/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 @@ -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; diff --git a/README.md b/README.md index fde762ca..89872b53 100644 --- a/README.md +++ b/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 diff --git a/APPSERVICES.md b/docs/configuration/appservices.md similarity index 99% rename from APPSERVICES.md rename to docs/configuration/appservices.md index a84f1d26..1445238d 100644 --- a/APPSERVICES.md +++ b/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` diff --git a/docs/configuration/conduit.toml.md b/docs/configuration/conduit.toml.md new file mode 100644 index 00000000..9a07facb --- /dev/null +++ b/docs/configuration/conduit.toml.md @@ -0,0 +1,2 @@ +# Configuring Conduit + diff --git a/docs/development/cross-compilation.md b/docs/development/cross-compilation.md new file mode 100644 index 00000000..d4d455fe --- /dev/null +++ b/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 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..a1c6726a --- /dev/null +++ b/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: \ +Bitcoin: `bc1qnnykf986tw49ur7wx9rpw2tevpsztvar5x8w4n` + + +[Matrix]: https://matrix.org/ +[Rust]: https://rust-lang.org +[Matrix Specification]: https://matrix.org/docs/spec \ No newline at end of file diff --git a/docs/installation/docker.md b/docs/installation/docker.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/installation/manual.md b/docs/installation/manual.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/installation/packages.md b/docs/installation/packages.md new file mode 100644 index 00000000..696398a1 --- /dev/null +++ b/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 +``` diff --git a/docs/installation/prerequisites.md b/docs/installation/prerequisites.md new file mode 100644 index 00000000..5e14d3dd --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/matrix-homeservers.md b/docs/matrix-homeservers.md new file mode 100644 index 00000000..caa590c7 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..dac38644 --- /dev/null +++ b/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 +