From 9ebb3fcd33b754189f601ca66453b62398d191f7 Mon Sep 17 00:00:00 2001 From: glyph Date: Fri, 13 Feb 2026 17:07:14 +0100 Subject: [PATCH 1/2] add installation instructions for nixos and revise sidebar structure for server section --- docs/setup/server/.nav.yml | 8 ++ docs/setup/server/index.md | 100 +++--------------- docs/setup/server/installation/bundle.md | 86 +++++++++++++++ .../setup/server/{ => installation}/docker.md | 0 docs/setup/server/installation/index.md | 11 ++ docs/setup/server/installation/nixos.md | 91 ++++++++++++++++ mkdocs.yml | 1 + requirements.txt | 5 +- 8 files changed, 213 insertions(+), 89 deletions(-) create mode 100644 docs/setup/server/.nav.yml create mode 100644 docs/setup/server/installation/bundle.md rename docs/setup/server/{ => installation}/docker.md (100%) create mode 100644 docs/setup/server/installation/index.md create mode 100644 docs/setup/server/installation/nixos.md diff --git a/docs/setup/server/.nav.yml b/docs/setup/server/.nav.yml new file mode 100644 index 00000000..d4a7f04c --- /dev/null +++ b/docs/setup/server/.nav.yml @@ -0,0 +1,8 @@ +nav: +- index.md +- installation/ +- configuration/ +- security/ +- maintenance/ +- adminApi/ +- "*" \ No newline at end of file diff --git a/docs/setup/server/index.md b/docs/setup/server/index.md index 058e3313..63768066 100644 --- a/docs/setup/server/index.md +++ b/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 }}. diff --git a/docs/setup/server/installation/bundle.md b/docs/setup/server/installation/bundle.md new file mode 100644 index 00000000..47eb500b --- /dev/null +++ b/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) diff --git a/docs/setup/server/docker.md b/docs/setup/server/installation/docker.md similarity index 100% rename from docs/setup/server/docker.md rename to docs/setup/server/installation/docker.md diff --git a/docs/setup/server/installation/index.md b/docs/setup/server/installation/index.md new file mode 100644 index 00000000..a4209410 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/setup/server/installation/nixos.md b/docs/setup/server/installation/nixos.md new file mode 100644 index 00000000..89da0b1f --- /dev/null +++ b/docs/setup/server/installation/nixos.md @@ -0,0 +1,91 @@ +# NixOS + +!!! warn "The NixOS module is still in development and subject to change." + +{{ 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, for example: + +```nix +apiEndpoint = { + useSsl = true; + host = "api.spacebar.mydomain.net"; + localPort = 3001; + publicPort = 443; # by default, if useSsl = 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) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 61e114d8..6b69363c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,7 @@ plugins: - section-index - search - macros + - awesome-nav theme: name: material logo: assets/logo.svg diff --git a/requirements.txt b/requirements.txt index 082a50ac..ea592049 100644 --- a/requirements.txt +++ b/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 \ No newline at end of file +mkdocs-macros-plugin==1.0.4 +mkdocs-awesome-nav==3 \ No newline at end of file From 6b38cfa4a5596a69be5935d1ebc28985456cf207 Mon Sep 17 00:00:00 2001 From: glyph Date: Fri, 13 Feb 2026 17:27:10 +0100 Subject: [PATCH 2/2] incorporate nixos module feedback --- docs/setup/server/installation/nixos.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/setup/server/installation/nixos.md b/docs/setup/server/installation/nixos.md index 89da0b1f..380d85c7 100644 --- a/docs/setup/server/installation/nixos.md +++ b/docs/setup/server/installation/nixos.md @@ -2,6 +2,8 @@ !!! 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 @@ -29,7 +31,7 @@ imports = [ 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, for example: +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 = { @@ -38,6 +40,8 @@ apiEndpoint = { 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`.