Merge branch 'docs' into 'next'

reduce scope of the documentation

See merge request famedly/conduit!607

docs/SUMMARY.md

@@ -3,10 +3,10 @@
 - [Introduction](introduction.md)
 
 - [Example configuration](configuration.md)
-- [Deployment options](deploying.md)
+- [Deploying](deploying.md)
-    - [Simple (Recommended)](deploying/simple.md)
+    - [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)

docs/deploying.md

@@ -1,8 +1,3 @@
-# Deployment options
+# Deploying
 
-There are several ways to deploy a Conduit server.
+This chapter describes various ways to deploy Conduit.
-
-- [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.

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.
 
@@ -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
 

docs/deploying/generic.md

@@ -1,6 +1,4 @@
-# Simple setup
+# Generic deployment documentation
-
-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
 >
@@ -61,26 +59,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.
-
-<details>
-<summary>Cross compilation</summary>
-
-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
-```
-</details>
-
 ## 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

docs/deploying/nix.md

@@ -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

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

flake.nix

@@ -307,6 +307,9 @@
 
           # Needed for finding broken markdown links
           lychee
+
+          # Useful for editing the book locally
+          mdbook
         ]);
       };
     });