From 68a33862b3a0298f3e478d94a0255bd95cb54326 Mon Sep 17 00:00:00 2001 From: Charles Hall Date: Thu, 21 Mar 2024 15:40:10 -0700 Subject: [PATCH 1/7] add mdbook to the devshell --- flake.nix | 3 +++ 1 file changed, 3 insertions(+) diff --git a/flake.nix b/flake.nix index 9cd826b8..fdaa0b67 100644 --- a/flake.nix +++ b/flake.nix @@ -307,6 +307,9 @@ # Needed for finding broken markdown links lychee + + # Useful for editing the book locally + mdbook ]); }; }); From 0a790686c57c087103ccbbaf9096d0eba6a2d753 Mon Sep 17 00:00:00 2001 From: Charles Hall Date: Thu, 21 Mar 2024 15:31:57 -0700 Subject: [PATCH 2/7] avoid duplicating links in documentation Because one might forget to update them. I did, initially, which is why I'm making this change. --- docs/deploying.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/deploying.md b/docs/deploying.md index 3694f6b2..4c4b154a 100644 --- a/docs/deploying.md +++ b/docs/deploying.md @@ -1,8 +1,3 @@ # 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. +This chapter describes various ways to deploy Conduit. From 2022efd2792034ab45a9e27db514744876009c93 Mon Sep 17 00:00:00 2001 From: Charles Hall Date: Thu, 21 Mar 2024 15:36:08 -0700 Subject: [PATCH 3/7] remove section about cross compilation It is very stale. Please just use Nix. Trying to do it outside of Nix will be an exercise in frustration, I guarantee it. --- docs/deploying/simple.md | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/docs/deploying/simple.md b/docs/deploying/simple.md index ea12a281..ef5c15d1 100644 --- a/docs/deploying/simple.md +++ b/docs/deploying/simple.md @@ -61,26 +61,6 @@ Then, `cd` into the source tree of conduit-next and run: $ cargo build --release ``` -If you want to cross compile Conduit to another architecture, read the guide below. - -
-Cross compilation - -As easiest way to compile conduit for another platform [cross-rs](https://github.com/cross-rs/cross) is recommended, so install it first. - -In order to use RockDB as storage backend append `-latomic` to linker flags. - -For example, to build a binary for Raspberry Pi Zero W (ARMv6) you need `arm-unknown-linux-gnueabihf` as compilation -target. - -```bash -git clone https://gitlab.com/famedly/conduit.git -cd conduit -export RUSTFLAGS='-C link-arg=-lgcc -Clink-arg=-latomic -Clink-arg=-static-libgcc' -cross build --release --no-default-features --features conduit_bin,backend_rocksdb,jemalloc --target=arm-unknown-linux-gnueabihf -``` -
- ## Adding a Conduit user While Conduit can run as any user it is usually better to use dedicated users for different services. This also allows From f56abba21651f64bf1b4f970ad0ca97c807256e8 Mon Sep 17 00:00:00 2001 From: Charles Hall Date: Thu, 21 Mar 2024 15:22:53 -0700 Subject: [PATCH 4/7] rename "simple" deployment to "generic" The main thing this section is really useful for is explaining how to configure various reverse proxies, which applies to basically anything. Also, remove all the language about this being "recommended", because nothing in this documentation is actually tested in CI. --- docs/SUMMARY.md | 2 +- docs/deploying/docker.md | 2 +- docs/deploying/{simple.md => generic.md} | 4 +--- 3 files changed, 3 insertions(+), 5 deletions(-) rename docs/deploying/{simple.md => generic.md} (98%) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index e7ed05d7..342d6957 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -4,7 +4,7 @@ - [Example configuration](configuration.md) - [Deployment options](deploying.md) - - [Simple (Recommended)](deploying/simple.md) + - [Generic](deploying/generic.md) - [Debian](deploying/debian.md) - [Docker](deploying/docker.md) - [Nix](deploying/nix.md) diff --git a/docs/deploying/docker.md b/docs/deploying/docker.md index 4a38b30b..20cd15f2 100644 --- a/docs/deploying/docker.md +++ b/docs/deploying/docker.md @@ -87,7 +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](simple.md). +Additional info about deploying Conduit can be found [here](generic.md). ### Build diff --git a/docs/deploying/simple.md b/docs/deploying/generic.md similarity index 98% rename from docs/deploying/simple.md rename to docs/deploying/generic.md index ef5c15d1..307de359 100644 --- a/docs/deploying/simple.md +++ b/docs/deploying/generic.md @@ -1,6 +1,4 @@ -# 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. +# Generic deployment documentation > ## Getting help > From f6bfba70146ea01ad00c526a022e6cad1c057e6c Mon Sep 17 00:00:00 2001 From: Charles Hall Date: Thu, 21 Mar 2024 15:28:19 -0700 Subject: [PATCH 5/7] normalize headers to "Conduit for X" --- docs/deploying/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deploying/docker.md b/docs/deploying/docker.md index 20cd15f2..c19ef51b 100644 --- a/docs/deploying/docker.md +++ b/docs/deploying/docker.md @@ -1,4 +1,4 @@ -# Deploy using Docker +# Conduit for Docker > **Note:** To run and use Conduit you should probably use it with a Domain or Subdomain behind a reverse proxy (like Nginx, Traefik, Apache, ...) with a Lets Encrypt certificate. From 3dd21456efe8c38aed4206f05042eddba1cbbc94 Mon Sep 17 00:00:00 2001 From: Charles Hall Date: Thu, 21 Mar 2024 15:25:34 -0700 Subject: [PATCH 6/7] reduce scope of nixos documentation There are so many ways to do this we realistically shouldn't bother describing any of them, especially because people should be learning all the options and choosing the one that suits them best anyway. --- docs/SUMMARY.md | 2 +- docs/deploying/nix.md | 198 ---------------------------------------- docs/deploying/nixos.md | 18 ++++ 3 files changed, 19 insertions(+), 199 deletions(-) delete mode 100644 docs/deploying/nix.md create mode 100644 docs/deploying/nixos.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 342d6957..89f620ea 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -7,6 +7,6 @@ - [Generic](deploying/generic.md) - [Debian](deploying/debian.md) - [Docker](deploying/docker.md) - - [Nix](deploying/nix.md) + - [NixOS](deploying/nixos.md) - [TURN](turn.md) - [Appservices](appservices.md) diff --git a/docs/deploying/nix.md b/docs/deploying/nix.md deleted file mode 100644 index bd6f0962..00000000 --- a/docs/deploying/nix.md +++ /dev/null @@ -1,198 +0,0 @@ -# Conduit for Nix/NixOS - -This guide assumes you have a recent version of Nix (^2.4) installed. - -Since Conduit ships as a Nix flake, you'll first need to [enable -flakes][enable_flakes]. - -You can now use the usual Nix commands to interact with Conduit's flake. For -example, `nix run gitlab:famedly/conduit` will run Conduit (though you'll need -to provide configuration and such manually as usual). - -If your NixOS configuration is defined as a flake, you can depend on this flake -to provide a more up-to-date version than provided by `nixpkgs`. In your flake, -add the following to your `inputs`: - -```nix -conduit = { - url = "gitlab:famedly/conduit"; - - # Assuming you have an input for nixpkgs called `nixpkgs`. If you experience - # build failures while using this, try commenting/deleting this line. This - # will probably also require you to always build from source. - inputs.nixpkgs.follows = "nixpkgs"; -}; -``` - -Next, make sure you're passing your flake inputs to the `specialArgs` argument -of `nixpkgs.lib.nixosSystem` [as explained here][specialargs]. This guide will -assume you've named the group `flake-inputs`. - -Now you can configure Conduit and a reverse proxy for it. Add the following to -a new Nix file and include it in your configuration: - -```nix -{ config -, pkgs -, flake-inputs -, ... -}: - -let - # You'll need to edit these values - - # The hostname that will appear in your user and room IDs - server_name = "example.com"; - - # The hostname that Conduit actually runs on - # - # This can be the same as `server_name` if you want. This is only necessary - # when Conduit is running on a different machine than the one hosting your - # root domain. This configuration also assumes this is all running on a single - # machine, some tweaks will need to be made if this is not the case. - matrix_hostname = "matrix.${server_name}"; - - # An admin email for TLS certificate notifications - admin_email = "admin@${server_name}"; - - # These ones you can leave alone - - # Build a dervation that stores the content of `${server_name}/.well-known/matrix/server` - well_known_server = pkgs.writeText "well-known-matrix-server" '' - { - "m.server": "${matrix_hostname}" - } - ''; - - # Build a dervation that stores the content of `${server_name}/.well-known/matrix/client` - well_known_client = pkgs.writeText "well-known-matrix-client" '' - { - "m.homeserver": { - "base_url": "https://${matrix_hostname}" - } - } - ''; -in - -{ - # Configure Conduit itself - services.matrix-conduit = { - enable = true; - - # This causes NixOS to use the flake defined in this repository instead of - # the build of Conduit built into nixpkgs. - package = flake-inputs.conduit.packages.${pkgs.system}.default; - - settings.global = { - inherit server_name; - }; - }; - - # Configure automated TLS acquisition/renewal - security.acme = { - acceptTerms = true; - defaults = { - email = admin_email; - }; - }; - - # ACME data must be readable by the NGINX user - users.users.nginx.extraGroups = [ - "acme" - ]; - - # Configure NGINX as a reverse proxy - services.nginx = { - enable = true; - recommendedProxySettings = true; - - virtualHosts = { - "${matrix_hostname}" = { - forceSSL = true; - enableACME = true; - - listen = [ - { - addr = "0.0.0.0"; - port = 443; - ssl = true; - } - { - addr = "[::]"; - port = 443; - ssl = true; - } { - addr = "0.0.0.0"; - port = 8448; - ssl = true; - } - { - addr = "[::]"; - port = 8448; - ssl = true; - } - ]; - - locations."/_matrix/" = { - proxyPass = "http://backend_conduit$request_uri"; - proxyWebsockets = true; - extraConfig = '' - proxy_set_header Host $host; - proxy_buffering off; - ''; - }; - - extraConfig = '' - merge_slashes off; - ''; - }; - - "${server_name}" = { - forceSSL = true; - enableACME = true; - - locations."=/.well-known/matrix/server" = { - # Use the contents of the derivation built previously - alias = "${well_known_server}"; - - extraConfig = '' - # Set the header since by default NGINX thinks it's just bytes - default_type application/json; - ''; - }; - - locations."=/.well-known/matrix/client" = { - # Use the contents of the derivation built previously - alias = "${well_known_client}"; - - extraConfig = '' - # Set the header since by default NGINX thinks it's just bytes - default_type application/json; - - # https://matrix.org/docs/spec/client_server/r0.4.0#web-browser-clients - add_header Access-Control-Allow-Origin "*"; - ''; - }; - }; - }; - - upstreams = { - "backend_conduit" = { - servers = { - "[::1]:${toString config.services.matrix-conduit.settings.global.port}" = { }; - }; - }; - }; - }; - - # Open firewall ports for HTTP, HTTPS, and Matrix federation - networking.firewall.allowedTCPPorts = [ 80 443 8448 ]; - networking.firewall.allowedUDPPorts = [ 80 443 8448 ]; -} -``` - -Now you can rebuild your system configuration and you should be good to go! - -[enable_flakes]: https://nixos.wiki/wiki/Flakes#Enable_flakes - -[specialargs]: https://nixos.wiki/wiki/Flakes#Using_nix_flakes_with_NixOS diff --git a/docs/deploying/nixos.md b/docs/deploying/nixos.md new file mode 100644 index 00000000..bf9b1a11 --- /dev/null +++ b/docs/deploying/nixos.md @@ -0,0 +1,18 @@ +# Conduit for NixOS + +Conduit can be acquired by Nix from various places: + +* The `flake.nix` at the root of the repo +* The `default.nix` at the root of the repo +* From Nixpkgs + +The `flake.nix` and `default.nix` do not (currently) provide a NixOS module, so +(for now) [`services.matrix-conduit`][module] from Nixpkgs should be used to +configure Conduit. + +If you want to run the latest code, you should get Conduit from the `flake.nix` +or `default.nix` and set [`services.matrix-conduit.package`][package] +appropriately. + +[module]: https://search.nixos.org/options?channel=unstable&query=services.matrix-conduit +[package]: https://search.nixos.org/options?channel=unstable&query=services.matrix-conduit.package From 5a4ee9808abeee0eedb932e4c02568d192ebdfca Mon Sep 17 00:00:00 2001 From: Charles Hall Date: Thu, 21 Mar 2024 15:42:36 -0700 Subject: [PATCH 7/7] make chapter name reflect file name Personally I think this makes more sense anyway. --- docs/SUMMARY.md | 2 +- docs/deploying.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 89f620ea..30316e27 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,7 +3,7 @@ - [Introduction](introduction.md) - [Example configuration](configuration.md) -- [Deployment options](deploying.md) +- [Deploying](deploying.md) - [Generic](deploying/generic.md) - [Debian](deploying/debian.md) - [Docker](deploying/docker.md) diff --git a/docs/deploying.md b/docs/deploying.md index 4c4b154a..136e6538 100644 --- a/docs/deploying.md +++ b/docs/deploying.md @@ -1,3 +1,3 @@ -# Deployment options +# Deploying This chapter describes various ways to deploy Conduit.