From 425660472cdbb66fd1bfea30f387598b680ed64a Mon Sep 17 00:00:00 2001 From: Samuel Meenzen Date: Wed, 13 Mar 2024 18:01:41 +0100 Subject: [PATCH] docs: build docs using mdBook --- .gitignore | 3 ++ .gitlab/route-map.yml | 3 ++ README.md | 31 ++++++++++--------- book.toml | 18 +++++++++++ debian/README.md | 2 +- docs/SUMMARY.md | 12 +++++++ APPSERVICES.md => docs/appservices.md | 0 docs/configuration.md | 5 +++ docs/deploying.md | 8 +++++ docs/deploying/debian.md | 1 + .../deploying}/docker-compose.for-traefik.yml | 0 .../deploying}/docker-compose.override.yml | 0 .../docker-compose.with-traefik.yml | 0 {docker => docs/deploying}/docker-compose.yml | 0 docker/README.md => docs/deploying/docker.md | 7 ++--- nix/README.md => docs/deploying/nix.md | 0 DEPLOY.md => docs/deploying/simple.md | 10 +++--- docs/introduction.md | 13 ++++++++ TURN.md => docs/turn.md | 2 +- 19 files changed, 90 insertions(+), 25 deletions(-) create mode 100644 .gitlab/route-map.yml create mode 100644 book.toml create mode 100644 docs/SUMMARY.md rename APPSERVICES.md => docs/appservices.md (100%) create mode 100644 docs/configuration.md create mode 100644 docs/deploying.md create mode 100644 docs/deploying/debian.md rename {docker => docs/deploying}/docker-compose.for-traefik.yml (100%) rename {docker => docs/deploying}/docker-compose.override.yml (100%) rename {docker => docs/deploying}/docker-compose.with-traefik.yml (100%) rename {docker => docs/deploying}/docker-compose.yml (100%) rename docker/README.md => docs/deploying/docker.md (97%) rename nix/README.md => docs/deploying/nix.md (100%) rename DEPLOY.md => docs/deploying/simple.md (97%) create mode 100644 docs/introduction.md rename TURN.md => docs/turn.md (97%) diff --git a/.gitignore b/.gitignore index a34d70ad..73ce2e1f 100644 --- a/.gitignore +++ b/.gitignore @@ -71,3 +71,6 @@ cached_target # Gitlab CI cache /.gitlab-ci.d + +# mdbook output +public/ \ No newline at end of file diff --git a/.gitlab/route-map.yml b/.gitlab/route-map.yml new file mode 100644 index 00000000..2c23079c --- /dev/null +++ b/.gitlab/route-map.yml @@ -0,0 +1,3 @@ +# Docs: Map markdown to html files +- source: /docs/(.+)\.md/ + public: '\1.html' \ No newline at end of file diff --git a/README.md b/README.md index bf7bde5e..0026f077 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,15 @@ # Conduit -### A Matrix homeserver written in Rust + +### A Matrix homeserver written in Rust + + +Please visit the [Conduit documentation](https://famedly.gitlab.io/conduit) for more information. +Alternatively you can open [docs/introduction.md](docs/introduction.md) in this repository. + + #### What is Matrix? + [Matrix](https://matrix.org) is an open network for secure and decentralized communication. Users from every Matrix homeserver can chat with users from all other Matrix servers. You can even use bridges (also called Matrix appservices) @@ -30,16 +38,9 @@ There are still a few important features missing: - E2EE emoji comparison over federation (E2EE chat works) - Outgoing read receipts, typing, presence over federation (incoming works) + -#### How can I deploy my own? - -- Simple install (this was tested the most): [DEPLOY.md](DEPLOY.md) -- Debian package: [debian/README.md](debian/README.md) -- Nix/NixOS: [nix/README.md](nix/README.md) -- Docker: [docker/README.md](docker/README.md) - -If you want to connect an Appservice to Conduit, take a look at [APPSERVICES.md](APPSERVICES.md). - + #### How can I contribute? 1. Look for an issue you would like to work on and make sure no one else is currently working on it. @@ -56,7 +57,6 @@ If you have any questions, feel free to - Send an direct message to `@timokoesters:fachschaften.org` on Matrix - [Open an issue on GitLab](https://gitlab.com/famedly/conduit/-/issues/new) - #### Thanks to Thanks to FUTO, Famedly, Prototype Fund (DLR and German BMBF) and all individuals for financially supporting this project. @@ -68,10 +68,11 @@ Thanks to the contributors to Conduit and all libraries we use, for example: #### Donate -Liberapay: \ -Bitcoin: `bc1qnnykf986tw49ur7wx9rpw2tevpsztvar5x8w4n` +- Liberapay: +- Bitcoin: `bc1qnnykf986tw49ur7wx9rpw2tevpsztvar5x8w4n` #### Logo -Lightning Bolt Logo: https://github.com/mozilla/fxemoji/blob/gh-pages/svgs/nature/u26A1-bolt.svg \ -Logo License: https://github.com/mozilla/fxemoji/blob/gh-pages/LICENSE.md +- Lightning Bolt Logo: +- Logo License: + diff --git a/book.toml b/book.toml new file mode 100644 index 00000000..e25746ca --- /dev/null +++ b/book.toml @@ -0,0 +1,18 @@ +[book] +title = "Conduit" +description = "Conduit is a simple, fast and reliable chat server for the Matrix protocol" +language = "en" +multilingual = false +src = "docs" + +[build] +build-dir = "public" +create-missing = true + +[output.html] +git-repository-url = "https://gitlab.com/famedly/conduit" +edit-url-template = "https://gitlab.com/famedly/conduit/-/edit/next/{path}" +git-repository-icon = "fa-git-square" + +[output.html.search] +limit-results = 15 diff --git a/debian/README.md b/debian/README.md index 443be76b..4ddb614d 100644 --- a/debian/README.md +++ b/debian/README.md @@ -5,7 +5,7 @@ Installation ------------ Information about downloading, building and deploying the Debian package, see -the "Installing Conduit" section in [DEPLOY.md](../DEPLOY.md). +the "Installing Conduit" section in the Deploying docs. All following sections until "Setting up the Reverse Proxy" be ignored because this is handled automatically by the packaging. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 00000000..e7ed05d7 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,12 @@ +# Summary + +- [Introduction](introduction.md) + +- [Example configuration](configuration.md) +- [Deployment options](deploying.md) + - [Simple (Recommended)](deploying/simple.md) + - [Debian](deploying/debian.md) + - [Docker](deploying/docker.md) + - [Nix](deploying/nix.md) +- [TURN](turn.md) +- [Appservices](appservices.md) diff --git a/APPSERVICES.md b/docs/appservices.md similarity index 100% rename from APPSERVICES.md rename to docs/appservices.md diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..a47e5ff9 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,5 @@ +# Example configuration + +``` toml +{{#include ../conduit-example.toml}} +``` diff --git a/docs/deploying.md b/docs/deploying.md new file mode 100644 index 00000000..3694f6b2 --- /dev/null +++ b/docs/deploying.md @@ -0,0 +1,8 @@ +# Deployment options + +There are several ways to deploy a Conduit server. + +- [Simple (Recommended)](deploying/simple.md) - This is the recommended way to set up Conduit. +- [Debian](deploying/debian.md) - If you're using a debian-based system, you may find the `deb` package useful. +- [Docker](deploying/docker.md) - We provide multi-arch OCI images for Conduit. +- [Nix](deploying/nix.md) - Nix flake based setup. diff --git a/docs/deploying/debian.md b/docs/deploying/debian.md new file mode 100644 index 00000000..2e8a544a --- /dev/null +++ b/docs/deploying/debian.md @@ -0,0 +1 @@ +{{#include ../../debian/README.md}} diff --git a/docker/docker-compose.for-traefik.yml b/docs/deploying/docker-compose.for-traefik.yml similarity index 100% rename from docker/docker-compose.for-traefik.yml rename to docs/deploying/docker-compose.for-traefik.yml diff --git a/docker/docker-compose.override.yml b/docs/deploying/docker-compose.override.yml similarity index 100% rename from docker/docker-compose.override.yml rename to docs/deploying/docker-compose.override.yml diff --git a/docker/docker-compose.with-traefik.yml b/docs/deploying/docker-compose.with-traefik.yml similarity index 100% rename from docker/docker-compose.with-traefik.yml rename to docs/deploying/docker-compose.with-traefik.yml diff --git a/docker/docker-compose.yml b/docs/deploying/docker-compose.yml similarity index 100% rename from docker/docker-compose.yml rename to docs/deploying/docker-compose.yml diff --git a/docker/README.md b/docs/deploying/docker.md similarity index 97% rename from docker/README.md rename to docs/deploying/docker.md index 2448e643..4a38b30b 100644 --- a/docker/README.md +++ b/docs/deploying/docker.md @@ -69,7 +69,7 @@ docker run -d -p 8448:6167 \ or you can use [docker-compose](#docker-compose). -The `-d` flag lets the container run in detached mode. You now need to supply a `conduit.toml` config file, an example can be found [here](../conduit-example.toml). +The `-d` flag lets the container run in detached mode. You now need to supply a `conduit.toml` config file, an example can be found [here](../configuration.md). You can pass in different env vars to change config values on the fly. You can even configure Conduit completely by using env vars, but for that you need to pass `-e CONDUIT_CONFIG=""` into your container. For an overview of possible values, please take a look at the `docker-compose.yml` file. @@ -87,8 +87,7 @@ Depending on your proxy setup, you can use one of the following files; When picking the traefik-related compose file, rename it so it matches `docker-compose.yml`, and rename the override file to `docker-compose.override.yml`. Edit the latter with the values you want for your server. - -Additional info about deploying Conduit can be found [here](../DEPLOY.md). +Additional info about deploying Conduit can be found [here](simple.md). ### Build @@ -130,7 +129,7 @@ So...step by step: 1. Copy [`docker-compose.for-traefik.yml`](docker-compose.for-traefik.yml) (or [`docker-compose.with-traefik.yml`](docker-compose.with-traefik.yml)) and [`docker-compose.override.yml`](docker-compose.override.yml) from the repository and remove `.for-traefik` (or `.with-traefik`) from the filename. 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. +3. Create the `conduit.toml` config file, an example can be found [here](../configuration.md), 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. diff --git a/nix/README.md b/docs/deploying/nix.md similarity index 100% rename from nix/README.md rename to docs/deploying/nix.md diff --git a/DEPLOY.md b/docs/deploying/simple.md similarity index 97% rename from DEPLOY.md rename to docs/deploying/simple.md index e87fca3b..9542bf1a 100644 --- a/DEPLOY.md +++ b/docs/deploying/simple.md @@ -1,4 +1,6 @@ -# Deploying Conduit +# Simple setup + +This is the recommended way to set up Conduit. It is the easiest way to get started and is suitable for most use cases. > ## Getting help > @@ -141,7 +143,7 @@ $ sudo systemctl daemon-reload Now we need to create the Conduit's config file in `/etc/matrix-conduit/conduit.toml`. Paste in the contents of -[`conduit-example.toml`](./conduit-example.toml) **and take a moment to read it. +[`conduit-example.toml`](../configuration.md) **and take a moment to read it. You need to change at least the server name.** You can also choose to use a different database backend, but right now only `rocksdb` and `sqlite` are recommended. @@ -305,8 +307,8 @@ $ curl https://your.server.name:8448/_matrix/client/versions ## Audio/Video calls -For Audio/Video call functionality see the [TURN Guide](TURN.md). +For Audio/Video call functionality see the [TURN Guide](../turn.md). ## Appservices -If you want to set up an appservice, take a look at the [Appservice Guide](APPSERVICES.md). +If you want to set up an appservice, take a look at the [Appservice Guide](../appservices.md). diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 00000000..da34ab6e --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,13 @@ +# Conduit + +{{#include ../README.md:catchphrase}} + +{{#include ../README.md:body}} + +#### How can I deploy my own? + +- [Deployment options](deploying.md) + +If you want to connect an Appservice to Conduit, take a look at the [appservices documentation](appservices.md). + +{{#include ../README.md:footer}} diff --git a/TURN.md b/docs/turn.md similarity index 97% rename from TURN.md rename to docs/turn.md index 63c1e99f..a61f1b13 100644 --- a/TURN.md +++ b/docs/turn.md @@ -22,4 +22,4 @@ turn_secret = "ADD SECRET HERE" ## Apply settings -Restart Conduit. \ No newline at end of file +Restart Conduit.