Add installation instructions for nixos

docs/setup/server/.nav.yml

@@ -0,0 +1,8 @@
+nav:
+- index.md
+- installation/
+- configuration/
+- security/
+- maintenance/
+- adminApi/
+- "*"

docs/setup/server/index.md

@@ -1,95 +1,21 @@
 # Server Setup
 
-{{ project.name }}-server setup ranges in difficulty depending on how you want to configure your system.
-This page provides a minimal setup guide to get you up and running,
-you should check out the other pages on this site to take your instance to the next level.
+A basic {{ project.name }} server setup consist of three services:
 
-For this guide, we assume you're familar with the terminal.
-
-We do **not** recommend or support running {{ project.name }} using services such as Ngrok, Heroku or vercel.  
-You **must** have access to a terminal for this guide.
-
-We do not recommend using Windows to run {{ project.name }}.
-
-## Dependencies
-
--   [Git](https://git-scm.com/)
--   [NodeJS](https://nodejs.org). Version 24+ (for `npm`, `node` commands)
-     (NOTE: Ubuntu and Debian based systems often ship with an outdated version of NodeJS, so you can use [NodeSource](https://github.com/nodesource/distributions) to install a newer version)
--   [Python](https://www.python.org/). Version 3.13 or later. Make sure this is executable via `python` in your terminal.  
-     (See: `python-is-python3` package)
--   [.NET SDK](https://dot.net). Version 9.0+. Optional, but used for the experimental [Admin API](adminApi).
--   On Linux: `gcc`/`g++`. Packaged with `build-essential` on Debian/Ubuntu and `base-devel` on Arch.
--   On Windows: [Visual Studio](https://visualstudio.microsoft.com/) (**NOT** VSCode) with the `Desktop development with C++` package.
-    You do not need the full Visual Studio install, the build tools are fine.
--   Hint: If you have the [`nix`](https://nixos.org/download/) package manager installed, you can skip all of the above by running `nix develop .#` in your terminal.
-
-## Setup
-
-In your terminal:
-
-```bash
-# Download {{ project.name }}
-git clone {{ repositories.base_url }}/{{ repositories.server }}.git
-
-# Navigate to project root
-cd server
-
-# Install javascript packages
-npm i
-
-# Build and generate schema + openapi. Separately, they are `build:src`, `generate:schema` and `generate:openapi`.
-npm run build
-
-# Start the bundle server ( API, CDN, Gateway in one )
-npm run start
-```
+- The API service provides a REST API for the client
+- The gateway service provides a websocket endpoint for the client
+- The CDN service serves static files such as uploaded images.
 
-If all went according to plan, you can now access your new {{ project.name }} instance at [http://localhost:3001](http://localhost:3001)! Congrats!
+In most cases you do not need to configure these services separately.
 
-If you set up your server remotely, you can use `curl http://localhost:3001/api/ping` to verify the server is up and running
-(you should set up a reverse proxy, next!).
+The following sections will guide you through the setup of a {{ project.name }} server:
 
-# Connecting from remote machines
+- [Installation](./installation/) explains how to install and run a server for the first time,
+- [Configuration](./configuration/) explains how to further configure your server to your needs,
+- [Security](./security/) contains details on how to harden a {{ project.name }} setup,
+- and a wide range of advanced topics can be found in the sidebar.
 
-For your server to be a bit more useful to those not on the same machine, you'll need to do a bit more configuration.
-
-The official Spacebar client does automatic discovery of the endpoints it uses to communicate with the server,
-but it needs to retrieve those from somewhere, that being the API server.
-
-If you don't tell the API server where to find the other services, the official Spacebar client wont be able to connect.
-Other clients which don't do automatic discovery will be, but that's because your users will need to provide the locations manually.
-
-We'll be doing some [server configuration](configuration) in this step, which is stored in your servers database by default.
-By default, Spacebar uses an SQLite database in the project root called `database.db`, but you might not want to use that for production.
-[If you're going to switch databases, do it now.](database.md)
-
-Once you've opened your database, navigate to the `config` table. You'll see 2 columns named `key` and `value`.
-You'll want to set the `value` of the rows with the following keys to the correct values.
-
-| key                      | value                                                    |
-| ------------------------ | -------------------------------------------------------- |
-| `api_endpointPublic`     | Your API endpoint. Likely `"https://DOMAIN_NAME/api/v9"` |
-| `cdn_endpointPublic`     | Your CDN endpoint. Likely `"https://DOMAIN_NAME"`         |
-| `gateway_endpointPublic` | Your Gateway endpoint. Likely `"wss://DOMAIN_NAME"`       |
-
-!!! warning "You must wrap these `value`s in doublequotes as they are parsed as JSON!"
-
-If you're in the CLI for this, heres some template SQL:
-
-=== "SQLite"
-
-    ```sql
-    update config
-    set value = '"HTTPS_OR_WSS://SERVER_ADDRESS"'
-    where key = "THE_SERVICE_NAME_endpointPublic";
-    ```
-
-## Now what?
-
-Well, now you can configure {{ project.name }} to your liking!
+For this guide, we assume you're familar with the terminal.
 
--   [Set up experimental and optional Admin API](adminApi)
--   [Skip to server configuration](configuration)
--   [Skip to reverse proxy / SSL](reverseProxy.md)
--   [Skip to security](security)
+We do **not** recommend or support running {{ project.name }} using services such as Ngrok, Heroku or vercel.  
+You **must** have access to a terminal for this guide. We do not recommend using Windows to run {{ project.name }}.

docs/setup/server/installation/bundle.md

@@ -0,0 +1,86 @@
+# NPM Bundle
+
+The easiest way to set up a {{ project.name }} server is by running the npm bundle, which runs the API, gateway, and CDN processes together.
+
+## Dependencies
+
+-   [Git](https://git-scm.com/)
+-   [NodeJS](https://nodejs.org). Version 24+ (for `npm`, `node` commands)
+     (NOTE: Ubuntu and Debian based systems often ship with an outdated version of NodeJS, so you can use [NodeSource](https://github.com/nodesource/distributions) to install a newer version)
+-   [Python](https://www.python.org/). Version 3.13 or later. Make sure this is executable via `python` in your terminal.  
+     (See: `python-is-python3` package)
+-   [.NET SDK](https://dot.net). Version 9.0+. Optional, but used for the experimental [Admin API](../adminApi).
+-   On Linux: `gcc`/`g++`. Packaged with `build-essential` on Debian/Ubuntu and `base-devel` on Arch.
+-   On Windows: [Visual Studio](https://visualstudio.microsoft.com/) (**NOT** VSCode) with the `Desktop development with C++` package.
+    You do not need the full Visual Studio install, the build tools are fine.
+-   Hint: If you have the [`nix`](https://nixos.org/download/) package manager installed, you can skip all of the above by running `nix develop .#` in your terminal.
+
+## Setup
+
+In your terminal:
+
+```bash
+# Download {{ project.name }}
+git clone {{ repositories.base_url }}/{{ repositories.server }}.git
+
+# Navigate to project root
+cd server
+
+# Install javascript packages
+npm i
+
+# Build and generate schema + openapi. Separately, they are `build:src`, `generate:schema` and `generate:openapi`.
+npm run build
+
+# Start the bundle server ( API, CDN, Gateway in one )
+npm run start
+```
+
+If all went according to plan, you can now access your new {{ project.name }} instance at [http://localhost:3001](http://localhost:3001)! Congrats!
+
+If you set up your server remotely, you can use `curl http://localhost:3001/api/ping` to verify the server is up and running
+(you should set up a reverse proxy, next!).
+
+# Connecting from remote machines
+
+For your server to be a bit more useful to those not on the same machine, you'll need to do a bit more configuration.
+
+The official Spacebar client does automatic discovery of the endpoints it uses to communicate with the server,
+but it needs to retrieve those from somewhere, that being the API server.
+
+If you don't tell the API server where to find the other services, the official Spacebar client wont be able to connect.
+Other clients which don't do automatic discovery will be, but that's because your users will need to provide the locations manually.
+
+We'll be doing some [server configuration](../configuration) in this step, which is stored in your servers database by default.
+By default, Spacebar uses an SQLite database in the project root called `database.db`, but you might not want to use that for production.
+[If you're going to switch databases, do it now.](../database.md)
+
+Once you've opened your database, navigate to the `config` table. You'll see 2 columns named `key` and `value`.
+You'll want to set the `value` of the rows with the following keys to the correct values.
+
+| key                      | value                                                    |
+| ------------------------ | -------------------------------------------------------- |
+| `api_endpointPublic`     | Your API endpoint. Likely `"https://DOMAIN_NAME/api/v9"` |
+| `cdn_endpointPublic`     | Your CDN endpoint. Likely `"https://DOMAIN_NAME"`         |
+| `gateway_endpointPublic` | Your Gateway endpoint. Likely `"wss://DOMAIN_NAME"`       |
+
+!!! warning "You must wrap these `value`s in doublequotes as they are parsed as JSON!"
+
+If you're in the CLI for this, heres some template SQL:
+
+=== "SQLite"
+
+    ```sql
+    update config
+    set value = '"HTTPS_OR_WSS://SERVER_ADDRESS"'
+    where key = "THE_SERVICE_NAME_endpointPublic";
+    ```
+
+## Now what?
+
+Well, now you can configure {{ project.name }} to your liking!
+
+-   [Set up experimental and optional Admin API](../adminApi)
+-   [Skip to server configuration](../configuration)
+-   [Skip to reverse proxy / SSL](../reverseProxy.md)
+-   [Skip to security](../security)

docs/setup/server/installation/index.md

@@ -0,0 +1,11 @@
+---
+weight: -100
+---
+
+# Installation
+
+{{ project.name }} supports the following installation methods:
+
+- [Bare Metal](bundle.md) as an npm bundle. Not recommended except for evaluation purposes.
+- [Docker](docker.md)
+- [NixOS](nixos.md)

docs/setup/server/installation/nixos.md

@@ -0,0 +1,95 @@
+# NixOS
+
+!!! warn "The NixOS module is still in development and subject to change."
+
+!!! warn "It is not currently possible to use the NixOS module outside flakes-based setups"
+
+{{ project.name }} comes with an integrated NixOS module, which takes care of a lot of the configuration for you. In particular, the module automatically configures [seperate SystemD services](../systemd.md) for the API, gateway, and CDN services and configures unix sockets for [message passing](../message-passing).
+
+## Installation
+
+Include the following dependency in your flake:
+
+```nix
+spacebar = {
+  url = "github:spacebarchat/server";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+```
+
+And import the spacebar module:
+
+```nix
+imports = [
+  spacebar.nixosModules.default
+];
+```
+
+## Configuration
+
+!!! warn "The options `enableAdminApi` and `enableCdnCs` currently have no effect and it is not recommended to use them."
+
+The module expose the option `services.spacebarchat-server`. You will want to set `serverName` to your instance domain. Additionally, you should point `requestSignaturePath` and `cdnSignaturePath` as files containing secrets for signing requests.
+
+The options `{api,gateway,cdn}Endpoint` should be configured for the connection information of the services. This can be done manually or by importing `${spacebar}/nix/modules/default/lib.nix` and using the function `mkEndpoint`. For example:
+
+```nix
+apiEndpoint = {
+  useSsl = true;
+  host = "api.spacebar.mydomain.net";
+  localPort = 3001;
+  publicPort = 443; # by default, if useSsl = true
+}
+
+gatewayEndpoint = (import "${spacebar}/nix/modules/default/lib.nix").mkEndpoint "gateway.spacebar.mydomain.net" 3002 true;
+```
+
+Nginx can be configured to act as a reverse proxy for those endpoints via `nginx.enable`.
+
+The configuration file is generated from `settings`. See [Configuration](../configuration/) for detailed documentation.
+
+Additional [environment variables](../configuration/env.md) can be set via `extraEnvironment` if desired. In particular, you will probably want to set up a [PostgreSQL database](../database.md) and set `extraEnvironemtn.DATABASE`. You can use
+
+```nix
+extraEnvironment.DATABASE = "postgres://?host=/run/postgresql";
+```
+
+if postgresql is running on the same host and local auth is enabled (by default on NixOS), or
+
+```nix
+extraEnvironment.DATABASE = "postgres://user:password@postgresql.host/spacebar"
+```
+
+for more involved setups.
+
+### Example Configuration
+
+A minimal configuration might look as follows:
+
+```nix
+spacebarchat-server = {
+  enable = true;
+  apiEndpoint = {
+    useSsl = false;
+    host = "api.sb.localhost";
+    localPort = 3001;
+    publicPort = 8080;
+  };
+  gatewayEndpoint = {
+    useSsl = false;
+    host = "gw.sb.localhost";
+    localPort = 3002;
+    publicPort = 8080;
+  };
+  cdnEndpoint = {
+    useSsl = false;
+    host = "cdn.sb.localhost";
+    localPort = 3003;
+    publicPort = 8080;
+  };
+  nginx.enable = true;
+  serverName = "sb.localhost";
+};
+```
+
+A more complicated setup can be found [here](https://cgit.rory.gay/Rory-Open-Architecture.git/tree/host/Rory-ovh/services/containers/spacebar/services/spacebar.nix)

mkdocs.yml

@@ -31,6 +31,7 @@ plugins:
     - section-index
     - search
     - macros
+    - awesome-nav
 theme:
     name: material
     logo: assets/logo.svg

requirements.txt

@@ -1,4 +1,5 @@
-mkdocs==1.5.2
+mkdocs==1.6
 mkdocs-material==9.1.21
 mkdocs-section-index==0.3.5
-mkdocs-macros-plugin==1.0.4
+mkdocs-macros-plugin==1.0.4
+mkdocs-awesome-nav==3