From e9ce642795fd86a91b2cfe286c6946febedd10ef Mon Sep 17 00:00:00 2001 From: Samuel Meenzen Date: Sun, 17 Mar 2024 18:06:10 -0400 Subject: [PATCH] docs: build docs using mdBook, build in CI, deploy to gitlab pages squashed from https://gitlab.com/famedly/conduit/-/merge_requests/604 added differences.md Co-authored-by: Charles Hall Co-authored-by: strawberry Signed-off-by: strawberry --- .gitignore | 3 ++ .gitlab-ci.yml | 17 ++++++++ .gitlab/route-map.yml | 3 ++ README.md | 40 ++++++++++--------- book.toml | 18 +++++++++ debian/README.md | 2 +- docs/SUMMARY.md | 13 ++++++ 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 | 6 +-- nix/README.md => docs/deploying/nix.md | 0 DEPLOY.md => docs/deploying/simple.md | 10 +++-- DIFFERENCES.md => docs/differences.md | 0 docs/introduction.md | 13 ++++++ TURN.md => docs/turn.md | 0 engage.toml | 10 +++++ flake.nix | 32 +++++++++++++++ 23 files changed, 154 insertions(+), 27 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 (96%) rename DIFFERENCES.md => docs/differences.md (100%) create mode 100644 docs/introduction.md rename TURN.md => docs/turn.md (100%) diff --git a/.gitignore b/.gitignore index 9a251d6bf..9b1e9d16b 100644 --- a/.gitignore +++ b/.gitignore @@ -75,5 +75,8 @@ test-conduit.toml # Gitlab CI cache /.gitlab-ci.d +# mdbook output +public/ + # macOS .DS_Store diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 154c3915a..348fcdd5e 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -105,6 +105,10 @@ artifacts: - ./bin/nix-build-and-cache .#oci-image-aarch64-unknown-linux-musl - cp result oci-image-arm64v8.tar.gz + + - ./bin/nix-build-and-cache .#book + # We can't just copy the symlink, we need to dereference it https://gitlab.com/gitlab-org/gitlab/-/issues/19746 + - cp -r --dereference result public artifacts: paths: - x86_64-unknown-linux-musl @@ -112,6 +116,7 @@ artifacts: - x86_64-unknown-linux-musl.deb - oci-image-amd64.tar.gz - oci-image-arm64v8.tar.gz + - public rules: # CI required for all MRs - if: $CI_PIPELINE_SOURCE == "merge_request_event" @@ -164,3 +169,15 @@ oci-image:push-gitlab: IMAGE_NAME: $CI_REGISTRY_IMAGE/conduwuit before_script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + +pages: + stage: publish + dependencies: + - artifacts + only: + - next + script: + - "true" + artifacts: + paths: + - public diff --git a/.gitlab/route-map.yml b/.gitlab/route-map.yml new file mode 100644 index 000000000..cf31bd188 --- /dev/null +++ b/.gitlab/route-map.yml @@ -0,0 +1,3 @@ +# Docs: Map markdown to html files +- source: /docs/(.+)\.md/ + public: '\1.html' diff --git a/README.md b/README.md index de0746f53..1bd598058 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,17 @@ # conduwuit -### a well maintained fork of [Conduit](https://conduit.rs/) [![CI and Artifacts](https://github.com/girlbossceo/conduwuit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/girlbossceo/conduwuit/actions/workflows/ci.yml) + +### a well maintained fork of [Conduit](https://conduit.rs/) + + +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) @@ -31,7 +39,7 @@ #### What is the current status? #### What's different about your fork than upstream Conduit? -See [DIFFERENCES.md](DIFFERENCES.md) +See [docs/differences.md](docs/differences.md) #### Why does this fork exist? Why don't you contribute back upstream? @@ -45,16 +53,9 @@ #### Why does this fork exist? Why don't you contribute back upstream? - Have a **stable** testing ground for some MRs or new features and bug fixes And various other reasons that may not be listed here. + -#### How can I deploy my own? - -conduwuit officially supports Linux, macOS, BSD, and Windows. - -- Simple install (this was tested the most): [DEPLOY.md](DEPLOY.md) -- Nix/NixOS (and binary cache): [nix/README.md](nix/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 it's not assigned @@ -72,9 +73,9 @@ #### Contact #### Donate -Liberapay: \ -Ko-fi: \ -GitHub Sponsors: +- Liberapay: +- Ko-fi: +- GitHub Sponsors: #### Logo @@ -86,8 +87,9 @@ #### Is it conduwuit or Conduwuit? #### Mirrors of conduwuit -GitHub: \ -GitLab: \ -git.gay: \ -Codeberg: \ -sourcehut: +- GitHub: +- GitLab: +- git.gay: +- Codeberg: +- sourcehut: + diff --git a/book.toml b/book.toml new file mode 100644 index 000000000..e25746ca5 --- /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 ff99dd939..063982de7 100644 --- a/debian/README.md +++ b/debian/README.md @@ -5,7 +5,7 @@ ------------ 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 000000000..c151756ee --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,13 @@ +# Summary + +- [Introduction](introduction.md) +- [Differences from upstream Conduit](differences.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 000000000..a47e5ff95 --- /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 000000000..3694f6b21 --- /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 000000000..2e8a544aa --- /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 eb2de450d..146a189ea 100644 --- a/docker/README.md +++ b/docs/deploying/docker.md @@ -70,7 +70,7 @@ ### Run 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](../conduwuit-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. @@ -89,7 +89,7 @@ ### Docker-compose 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 @@ -131,7 +131,7 @@ ### Use Traefik as Proxy 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](../conduwuit-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 96% rename from DEPLOY.md rename to docs/deploying/simple.md index 433a24d51..0fd8dce63 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. ### Please note that this documentation is not fully representative of conduwuit at the moment. Assume majority of it is outdated. @@ -118,7 +120,7 @@ ## Creating the Conduit configuration file 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. -See the following example config at [conduwuit-example.toml](conduwuit-example.toml) +See the following example config at [conduwuit-example.toml](../configuration.md) ## Setting the correct file permissions @@ -300,8 +302,8 @@ # What's next? ## 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/DIFFERENCES.md b/docs/differences.md similarity index 100% rename from DIFFERENCES.md rename to docs/differences.md diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 000000000..da34ab6eb --- /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 100% rename from TURN.md rename to docs/turn.md diff --git a/engage.toml b/engage.toml index ce47452c1..1f9684670 100644 --- a/engage.toml +++ b/engage.toml @@ -50,6 +50,11 @@ name = "cargo-deb" group = "versions" script = "cargo deb --version" +[[task]] +name = "lychee" +group = "versions" +script = "lychee --version" + [[task]] name = "cargo-audit" group = "security" @@ -77,6 +82,11 @@ name = "cargo-clippy" group = "lints" script = "cargo clippy --workspace --all-targets --all-features --color=always -- -D warnings" +[[task]] +name = "lychee" +group = "lints" +script = "lychee --offline docs" + [[task]] name = "cargo" group = "tests" diff --git a/flake.nix b/flake.nix index f0e51df9b..346fb9112 100644 --- a/flake.nix +++ b/flake.nix @@ -208,6 +208,35 @@ packages = { default = package pkgsHost; oci-image = mkOciImage pkgsHost self.packages.${system}.default; + + book = + let + package = self.packages.${system}.default; + in + pkgsHost.stdenv.mkDerivation { + pname = "${package.pname}-book"; + version = package.version; + + src = nix-filter { + root = ./.; + include = [ + "book.toml" + "conduit-example.toml" + "README.md" + "debian/README.md" + "docs" + ]; + }; + + nativeBuildInputs = (with pkgsHost; [ + mdbook + ]); + + buildPhase = '' + mdbook build + mv public $out + ''; + }; } // builtins.listToAttrs @@ -276,6 +305,9 @@ # Needed for our script for Complement jq + + # Needed for finding broken markdown links + lychee ]); }; });