Skip to content

Commit 9ebb3fc

Browse files
author
glyph
committed
add installation instructions for nixos and revise sidebar structure for server section
1 parent e89b1d5 commit 9ebb3fc

8 files changed

Lines changed: 213 additions & 89 deletions

File tree

‎docs/setup/server/.nav.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
nav:
2+
- index.md
3+
- installation/
4+
- configuration/
5+
- security/
6+
- maintenance/
7+
- adminApi/
8+
- "*"

‎docs/setup/server/index.md‎

Lines changed: 13 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,21 @@
11
# Server Setup
22

3-
{{ project.name }}-server setup ranges in difficulty depending on how you want to configure your system.
4-
This page provides a minimal setup guide to get you up and running,
5-
you should check out the other pages on this site to take your instance to the next level.
3+
A basic {{ project.name }} server setup consist of three services:
64

7-
For this guide, we assume you're familar with the terminal.
8-
9-
We do **not** recommend or support running {{ project.name }} using services such as Ngrok, Heroku or vercel.
10-
You **must** have access to a terminal for this guide.
11-
12-
We do not recommend using Windows to run {{ project.name }}.
13-
14-
## Dependencies
15-
16-
- [Git](https://git-scm.com/)
17-
- [NodeJS](https://nodejs.org). Version 24+ (for `npm`, `node` commands)
18-
(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)
19-
- [Python](https://www.python.org/). Version 3.13 or later. Make sure this is executable via `python` in your terminal.
20-
(See: `python-is-python3` package)
21-
- [.NET SDK](https://dot.net). Version 9.0+. Optional, but used for the experimental [Admin API](adminApi).
22-
- On Linux: `gcc`/`g++`. Packaged with `build-essential` on Debian/Ubuntu and `base-devel` on Arch.
23-
- On Windows: [Visual Studio](https://visualstudio.microsoft.com/) (**NOT** VSCode) with the `Desktop development with C++` package.
24-
You do not need the full Visual Studio install, the build tools are fine.
25-
- 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.
26-
27-
## Setup
28-
29-
In your terminal:
30-
31-
```bash
32-
# Download {{ project.name }}
33-
git clone {{ repositories.base_url }}/{{ repositories.server }}.git
34-
35-
# Navigate to project root
36-
cd server
37-
38-
# Install javascript packages
39-
npm i
40-
41-
# Build and generate schema + openapi. Separately, they are `build:src`, `generate:schema` and `generate:openapi`.
42-
npm run build
43-
44-
# Start the bundle server ( API, CDN, Gateway in one )
45-
npm run start
46-
```
5+
- The API service provides a REST API for the client
6+
- The gateway service provides a websocket endpoint for the client
7+
- The CDN service serves static files such as uploaded images.
478

48-
If all went according to plan, you can now access your new {{ project.name }} instance at [http://localhost:3001](http://localhost:3001)! Congrats!
9+
In most cases you do not need to configure these services separately.
4910

50-
If you set up your server remotely, you can use `curl http://localhost:3001/api/ping` to verify the server is up and running
51-
(you should set up a reverse proxy, next!).
11+
The following sections will guide you through the setup of a {{ project.name }} server:
5212

53-
# Connecting from remote machines
13+
- [Installation](./installation/) explains how to install and run a server for the first time,
14+
- [Configuration](./configuration/) explains how to further configure your server to your needs,
15+
- [Security](./security/) contains details on how to harden a {{ project.name }} setup,
16+
- and a wide range of advanced topics can be found in the sidebar.
5417

55-
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.
56-
57-
The official Spacebar client does automatic discovery of the endpoints it uses to communicate with the server,
58-
but it needs to retrieve those from somewhere, that being the API server.
59-
60-
If you don't tell the API server where to find the other services, the official Spacebar client wont be able to connect.
61-
Other clients which don't do automatic discovery will be, but that's because your users will need to provide the locations manually.
62-
63-
We'll be doing some [server configuration](configuration) in this step, which is stored in your servers database by default.
64-
By default, Spacebar uses an SQLite database in the project root called `database.db`, but you might not want to use that for production.
65-
[If you're going to switch databases, do it now.](database.md)
66-
67-
Once you've opened your database, navigate to the `config` table. You'll see 2 columns named `key` and `value`.
68-
You'll want to set the `value` of the rows with the following keys to the correct values.
69-
70-
| key | value |
71-
| ------------------------ | -------------------------------------------------------- |
72-
| `api_endpointPublic` | Your API endpoint. Likely `"https://DOMAIN_NAME/api/v9"` |
73-
| `cdn_endpointPublic` | Your CDN endpoint. Likely `"https://DOMAIN_NAME"` |
74-
| `gateway_endpointPublic` | Your Gateway endpoint. Likely `"wss://DOMAIN_NAME"` |
75-
76-
!!! warning "You must wrap these `value`s in doublequotes as they are parsed as JSON!"
77-
78-
If you're in the CLI for this, heres some template SQL:
79-
80-
=== "SQLite"
81-
82-
```sql
83-
update config
84-
set value = '"HTTPS_OR_WSS://SERVER_ADDRESS"'
85-
where key = "THE_SERVICE_NAME_endpointPublic";
86-
```
87-
88-
## Now what?
89-
90-
Well, now you can configure {{ project.name }} to your liking!
18+
For this guide, we assume you're familar with the terminal.
9119

92-
- [Set up experimental and optional Admin API](adminApi)
93-
- [Skip to server configuration](configuration)
94-
- [Skip to reverse proxy / SSL](reverseProxy.md)
95-
- [Skip to security](security)
20+
We do **not** recommend or support running {{ project.name }} using services such as Ngrok, Heroku or vercel.
21+
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‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# NPM Bundle
2+
3+
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.
4+
5+
## Dependencies
6+
7+
- [Git](https://git-scm.com/)
8+
- [NodeJS](https://nodejs.org). Version 24+ (for `npm`, `node` commands)
9+
(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)
10+
- [Python](https://www.python.org/). Version 3.13 or later. Make sure this is executable via `python` in your terminal.
11+
(See: `python-is-python3` package)
12+
- [.NET SDK](https://dot.net). Version 9.0+. Optional, but used for the experimental [Admin API](../adminApi).
13+
- On Linux: `gcc`/`g++`. Packaged with `build-essential` on Debian/Ubuntu and `base-devel` on Arch.
14+
- On Windows: [Visual Studio](https://visualstudio.microsoft.com/) (**NOT** VSCode) with the `Desktop development with C++` package.
15+
You do not need the full Visual Studio install, the build tools are fine.
16+
- 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.
17+
18+
## Setup
19+
20+
In your terminal:
21+
22+
```bash
23+
# Download {{ project.name }}
24+
git clone {{ repositories.base_url }}/{{ repositories.server }}.git
25+
26+
# Navigate to project root
27+
cd server
28+
29+
# Install javascript packages
30+
npm i
31+
32+
# Build and generate schema + openapi. Separately, they are `build:src`, `generate:schema` and `generate:openapi`.
33+
npm run build
34+
35+
# Start the bundle server ( API, CDN, Gateway in one )
36+
npm run start
37+
```
38+
39+
If all went according to plan, you can now access your new {{ project.name }} instance at [http://localhost:3001](http://localhost:3001)! Congrats!
40+
41+
If you set up your server remotely, you can use `curl http://localhost:3001/api/ping` to verify the server is up and running
42+
(you should set up a reverse proxy, next!).
43+
44+
# Connecting from remote machines
45+
46+
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.
47+
48+
The official Spacebar client does automatic discovery of the endpoints it uses to communicate with the server,
49+
but it needs to retrieve those from somewhere, that being the API server.
50+
51+
If you don't tell the API server where to find the other services, the official Spacebar client wont be able to connect.
52+
Other clients which don't do automatic discovery will be, but that's because your users will need to provide the locations manually.
53+
54+
We'll be doing some [server configuration](../configuration) in this step, which is stored in your servers database by default.
55+
By default, Spacebar uses an SQLite database in the project root called `database.db`, but you might not want to use that for production.
56+
[If you're going to switch databases, do it now.](../database.md)
57+
58+
Once you've opened your database, navigate to the `config` table. You'll see 2 columns named `key` and `value`.
59+
You'll want to set the `value` of the rows with the following keys to the correct values.
60+
61+
| key | value |
62+
| ------------------------ | -------------------------------------------------------- |
63+
| `api_endpointPublic` | Your API endpoint. Likely `"https://DOMAIN_NAME/api/v9"` |
64+
| `cdn_endpointPublic` | Your CDN endpoint. Likely `"https://DOMAIN_NAME"` |
65+
| `gateway_endpointPublic` | Your Gateway endpoint. Likely `"wss://DOMAIN_NAME"` |
66+
67+
!!! warning "You must wrap these `value`s in doublequotes as they are parsed as JSON!"
68+
69+
If you're in the CLI for this, heres some template SQL:
70+
71+
=== "SQLite"
72+
73+
```sql
74+
update config
75+
set value = '"HTTPS_OR_WSS://SERVER_ADDRESS"'
76+
where key = "THE_SERVICE_NAME_endpointPublic";
77+
```
78+
79+
## Now what?
80+
81+
Well, now you can configure {{ project.name }} to your liking!
82+
83+
- [Set up experimental and optional Admin API](../adminApi)
84+
- [Skip to server configuration](../configuration)
85+
- [Skip to reverse proxy / SSL](../reverseProxy.md)
86+
- [Skip to security](../security)

docs/setup/server/docker.md renamed to docs/setup/server/installation/docker.md

File renamed without changes.

‎docs/setup/server/installation/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
weight: -100
3+
---
4+
5+
# Installation
6+
7+
{{ project.name }} supports the following installation methods:
8+
9+
- [Bare Metal](bundle.md) as an npm bundle. Not recommended except for evaluation purposes.
10+
- [Docker](docker.md)
11+
- [NixOS](nixos.md)

‎docs/setup/server/installation/nixos.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# NixOS
2+
3+
!!! warn "The NixOS module is still in development and subject to change."
4+
5+
{{ 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).
6+
7+
## Installation
8+
9+
Include the following dependency in your flake:
10+
11+
```nix
12+
spacebar = {
13+
url = "github:spacebarchat/server";
14+
inputs.nixpkgs.follows = "nixpkgs";
15+
};
16+
```
17+
18+
And import the spacebar module:
19+
20+
```nix
21+
imports = [
22+
spacebar.nixosModules.default
23+
];
24+
```
25+
26+
## Configuration
27+
28+
!!! warn "The options `enableAdminApi` and `enableCdnCs` currently have no effect and it is not recommended to use them."
29+
30+
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.
31+
32+
The options `{api,gateway,cdn}Endpoint` should be configured for the connection information of the services, for example:
33+
34+
```nix
35+
apiEndpoint = {
36+
useSsl = true;
37+
host = "api.spacebar.mydomain.net";
38+
localPort = 3001;
39+
publicPort = 443; # by default, if useSsl = true
40+
}
41+
```
42+
43+
Nginx can be configured to act as a reverse proxy for those endpoints via `nginx.enable`.
44+
45+
The configuration file is generated from `settings`. See [Configuration](../configuration/) for detailed documentation.
46+
47+
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
48+
49+
```nix
50+
extraEnvironment.DATABASE = "postgres://?host=/run/postgresql";
51+
```
52+
53+
if postgresql is running on the same host and local auth is enabled (by default on NixOS), or
54+
55+
```nix
56+
extraEnvironment.DATABASE = "postgres://user:password@postgresql.host/spacebar"
57+
```
58+
59+
for more involved setups.
60+
61+
### Example Configuration
62+
63+
A minimal configuration might look as follows:
64+
65+
```nix
66+
spacebarchat-server = {
67+
enable = true;
68+
apiEndpoint = {
69+
useSsl = false;
70+
host = "api.sb.localhost";
71+
localPort = 3001;
72+
publicPort = 8080;
73+
};
74+
gatewayEndpoint = {
75+
useSsl = false;
76+
host = "gw.sb.localhost";
77+
localPort = 3002;
78+
publicPort = 8080;
79+
};
80+
cdnEndpoint = {
81+
useSsl = false;
82+
host = "cdn.sb.localhost";
83+
localPort = 3003;
84+
publicPort = 8080;
85+
};
86+
nginx.enable = true;
87+
serverName = "sb.localhost";
88+
};
89+
```
90+
91+
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‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ plugins:
3131
- section-index
3232
- search
3333
- macros
34+
- awesome-nav
3435
theme:
3536
name: material
3637
logo: assets/logo.svg

‎requirements.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
mkdocs==1.5.2
1+
mkdocs==1.6
22
mkdocs-material==9.1.21
33
mkdocs-section-index==0.3.5
4-
mkdocs-macros-plugin==1.0.4
4+
mkdocs-macros-plugin==1.0.4
5+
mkdocs-awesome-nav==3

0 commit comments

Comments
 (0)