Skip to content

Commit 84e9a51

Browse files
TheArcaneBronyTheArcaneBrony
authored
Merge pull request #116 from strangeglyph/nixos-installation-instructions
Add installation instructions for nixos
2 parents a41a5f1 + 6b38cfa commit 84e9a51

8 files changed

Lines changed: 264 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/installation/docker.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Running the server as a docker container
2+
3+
## Bundle
4+
5+
1. Add an isolated network to share between the server and the database:
6+
```sh
7+
docker network create spacebar-network
8+
```
9+
10+
2. Set up a database for the server:
11+
```sh
12+
docker run \
13+
-d \
14+
--name spacebar-db \
15+
--network spacebar-network \
16+
-e POSTGRES_PASSWORD=postgres \
17+
-v spacebar-db:/var/lib/postgresql \
18+
postgres:alpine
19+
```
20+
21+
3. Run the server docker image to let it generate the config:
22+
```sh
23+
docker run \
24+
--rm \
25+
--name spacebar-server \
26+
--network spacebar-network \
27+
-e DATABASE=postgres://postgres:postgres@spacebar-db/postgres \
28+
-e CONFIG_PATH=config/config.json \
29+
-v ./config:/config \
30+
-v ./files:/files \
31+
ghcr.io/{{ repositories.server }}
32+
```
33+
34+
4. Set config values for `general_serverName`, `cdn_endpointPublic`, `cdn_endpointPrivate` to `http://localhost:3001`, `api_endpointPublic` to `http://localhost:3001/api/v9` and `gateway_endpointPublic` to `ws://localhost:3001`
35+
36+
5. Run the server docker image after the config changes:
37+
```sh
38+
docker run \
39+
--name spacebar-server \
40+
--network spacebar-network \
41+
-e DATABASE=postgres://postgres:postgres@spacebar-db/postgres \
42+
-e CONFIG_PATH=config/config.json \
43+
-v ./config:/config \
44+
-v ./files:/files \
45+
-p 3001:3001 \
46+
ghcr.io/{{ repositories.server }}
47+
```

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