Added documentation for the numbus-server

2026-03-18 13:26:13 +01:00
parent d09e261b14
commit b156bf443e
20 changed files with 581 additions and 161 deletions
@@ -0,0 +1,45 @@
+# Numbus documentation
+
+<img title="Numbus Logo" src="./logo.png" alt="The Numbus logo" width="220">
+
+## Deployment process overview
+
+<img title="Overview of the deployment process" src="./deployment_overview.png" alt="A graph showing an overview of the deployment process" width="525">
+
+## Table of contents
+
+### [Numbus Server](https://gittea.dev/numbus/numbus-server)
+
+* [Presentation](https://gittea.dev/numbus/numbus-server)
+* [Requirements](./numbus-server/requirements.md)
+* [Configuration](./numbus-server/configuration/index.md)
+* [Deployment](./numbus-server/deployment/index.md)
+* [Updates](./numbus-server/updates/index.md)
+* [Maintenance](./numbus-server/maintenance/index.md)
+
+### [Numbus Backup Server](https://gittea.dev/numbus/numbus-backup-server)
+
+* [Presentation](https://gittea.dev/numbus/numbus-backup-server)
+* [Requirements](./numbus-backup-server/requirements.md)
+* [Configuration](./numbus-backup-server/configuration/index.md)
+* [Deployment](./numbus-backup-server/deployment/index.md)
+* [Updates](./numbus-backup-server/updates/index.md)
+* [Maintenance](./numbus-backup-server/maintenance/index.md)
+
+### [Numbus Computer](https://gittea.dev/numbus/numbus-computer)
+
+* [Presentation](https://gittea.dev/numbus/numbus-computer)
+* [Requirements](./numbus-computer/requirements.md)
+* [Configuration](./numbus-computer/configuration/index.md)
+* [Deployment](./numbus-computer/deployment/index.md)
+* [Updates](./numbus-computer/updates/index.md)
+* [Maintenance](./numbus-computer/maintenance/index.md)
+
+### [Numbus TV](https://gittea.dev/numbus/numbus-tv)
+
+* [Presentation](https://gittea.dev/numbus/numbus-tv)
+* [Requirements](./numbus-tv/requirements.md)
+* [Configuration](./numbus-tv/configuration/index.md)
+* [Deployment](./numbus-tv/deployment/index.md)
+* [Updates](./numbus-tv/updates/index.md)
+* [Maintenance](./numbus-tv/maintenance/index.md)
@@ -0,0 +1,31 @@
+# Requirements
+
+### To deploy
+
+To deploy a numbus-backup-server, you will need :
+
+* A **live NixOS** bootable USB disk.
+
+You will make the **target** machine **boot** into the NixOS live environment using this **USB stick**. Download the [NixOS iso](https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso) image.
+
+*On Linux* : Flash it using [Impression (flatpak)](https://flathub.org/en/apps/io.gitlab.adhami3310.Impression) or [BalenaEtcher (AppImage)](https://etcher.balena.io/#download-etcher).
+
+*On MacOS* : Flash it using [BalenaEtcher](https://etcher.balena.io/#download-etcher).
+
+*On Windows* : Flash it using [Rufus](https://rufus.ie/en/#download) or [BalenaEtcher](https://etcher.balena.io/#download-etcher).
+
+* **Source** Machine:
+
+Can be any machine with **Nix installed**, e.g. a **NixOS** machine.
+
+* **Target** Machine:
+
+Can be **any computer** (desktop, SFF, tiny/mini/micro, even a laptop). It could be a dedicated server that you bought or just some computer that you decided to repurpose into a backup server.
+
+* **Network connection** between the source and the target machine.
+
+---
+
+### Next step
+
+[Configuration](./configuration/index.md)
@@ -0,0 +1,31 @@
+# Requirements
+
+### To deploy
+
+To deploy a numbus-backup-server, you will need :
+
+* A **live NixOS** bootable USB disk.
+
+You will make the **target** machine **boot** into the NixOS live environment using this **USB stick**. Download the [NixOS iso](https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso) image.
+
+*On Linux* : Flash it using [Impression (flatpak)](https://flathub.org/en/apps/io.gitlab.adhami3310.Impression) or [BalenaEtcher (AppImage)](https://etcher.balena.io/#download-etcher).
+
+*On MacOS* : Flash it using [BalenaEtcher](https://etcher.balena.io/#download-etcher).
+
+*On Windows* : Flash it using [Rufus](https://rufus.ie/en/#download) or [BalenaEtcher](https://etcher.balena.io/#download-etcher).
+
+* **Source** Machine:
+
+Can be any machine with **Nix installed**, e.g. a **NixOS** machine.
+
+* **Target** Machine:
+
+Can be **any computer** (desktop, SFF, tiny/mini/micro, even a laptop). It could be a dedicated server that you bought or just some computer that you decided to repurpose into a backup server.
+
+* **Network connection** between the source and the target machine.
+
+---
+
+### Next step
+
+[Configuration](./configuration/index.md)
@@ -0,0 +1,7 @@
+# Documentation
+
+## 🚦 Configuring Traefik
+
+| Variable | Description | Values | Default |
+| -------- | ----------- | ------ | --------- | 
+| CLOUDFLARE_DNS_API_TOKEN | The Cloudflare API token with "Zone.DNS" permissions, used for SSL certificate generation. | "bA7hdvCOuXGytlNKohi3ZGtlVpf5CHpLuCMiJrE" | null. Not setting this variable will cause the script to fail. |
@@ -0,0 +1,19 @@
+# Documentation
+
+## ✏️ Filling the configuration file
+
+You can deploy the numbus-server without using a configuration file, **but I would strongly advise it** as it diminishes the risk of **typos** when providing credentials. It also creates a file that you can **keep**, **reuse**, **consult** whenever you are **in doubt** about a certain setting.
+
+> 🚀 Let's fill this configuration file !
+
+The configuration file is divided into **multiple categories**. Some of them are **optional**, some are **mandatory**. Here is the list of categories :
+
+| Category | Available variables |
+| -------- | ------------------  |
+| [Live target settings](./live_target.md) | 2 |
+| [Server settings](/.server.md) | 7 |
+| [Mail settings](./mail.md) | 4 |
+| [Traefik settings](./automatic_ssl_certs.md) | 1 |
+| [Network settings](./network.md) | 3 |
+| [Services selection](./services/index.md) | 5 |
+| [Script settings](./script.md) | 1 |
@@ -0,0 +1,8 @@
+# Documentation
+
+### 📦 Configuring the target settings
+
+| Variable | Description | Values | Default |
+| -------- | ----------- | ------- | --------- | 
+| LIVE_TARGET_IP | The IP address of the target machine. Without the CIDR notation. | "192.168.1.28", "10.10.10.45", ... |  |
+| LIVE_TARGET_PASSWD | The password of the target machine that you set using the `passwd` command. | "my-password", ... |  |
@@ -0,0 +1,24 @@
+# Documentation
+
+## 📬 Configuring the mail settings
+
+| Variable | Description | Values | Default |
+| -------- | ----------- | ------ | --------- | 
+| SMTP_SERVER_USERNAME | The email address used to send automated emails (alerts, notifications). | "your-address@your-domain.com" |  |
+| SMTP_SERVER_PASSWORD | The password or app-specific password for the email account. | "your-secure-password" |  |
+| SMTP_SERVER_HOST | The address of the SMTP server. | "smtp.yourdomain.com" | "smtp.gmail.com" |
+| SMTP_SERVER_PORT | The port number for the SMTP server. | "587" or "465" | "587" |
+
+## ❓ I don't already have an SMTP capable email
+
+If your provider doesn't support **standard SMTP**, the easiest solution is to create a **free Gmail account** dedicated to your server. 
+
+Gmail allows you to generate an **App Password** which works perfectly for automated alerts.
+
+1. Navigate to the [Google account creation page](https://accounts.google.com/signup). Follow the prompts to create your account. Feel free **not to provide** real information about yourself. Giving your phone number and home address is **not needed**.
+
+2. Once your account is **created** navigate to the [Google account settings](https://myaccount.google.com).
+
+3. In the security page, enable the **two factor authentication (2FA)**. The best way to enable 2FA without providing too much information is using **TOTP codes** (under Authenticator label). You can use the open-source [Ente Auth](https://ente.io/auth/) app to get your **TOTP codes**.
+
+4. Finally, once **2FA** is enabled, you can generate an **app password**. Navigate to the [app passwords page](https://myaccount.google.com/apppasswords). Generate an app password and call it "numbus-server" to **remember** what it is used for.
@@ -0,0 +1,9 @@
+# Documentation
+
+## 🛜 Configuring the server's network settings
+
+| Variable | Description | Values | Default |
+| -------- | ----------- | ------ | --------- | 
+| NETWORK_SUBNET | The local network subnet in CIDR notation. | "192.168.1.0/24", "10.10.10.0/24", ... | "192.168.1.0/24" |
+| NETWORK_ROUTER_IP | The IP address of your internet router/gateway. | "192.168.1.1", "192.168.1.254", ... | "192.168.1.1" |
+| HOME_SERVER_IP | The static IP address to assign to this server (must be outside the router's DHCP range). | "192.168.1.5", "192.168.0.200", ... | "192.168.1.254" |
@@ -0,0 +1,7 @@
+# Documentation
+
+## 📜 Configuring the script's settings
+
+| Variable | Description | Values | Default |
+| -------- | ----------- | ------ | --------- | 
+| VERBOSE | Enables verbose logging for the deployment script (useful for debugging). | "true" or "false" | "false" |
@@ -0,0 +1,13 @@
+# Documentation
+
+## ⚙️ Configuring the server settings
+
+| Variable | Description | Values | Default |
+| -------- | ----------- | ------ | --------- | 
+| SERVER_LANGUAGE | The desired language for the server's system and services. | "FR", "DE", "UK", ... | "FR" |
+| SERVER_LOCALE | Defines the server's regional settings, including date, time, and number formatting. | "fr_FR", "de_DE", "en_UK", ... | "fr_FR" |
+| SERVER_TIMEZONE | Sets the server's timezone to ensure accurate timekeeping for logs and services. | "Europe/Paris", "Europe/Berlin", "Europe/London", ... | "Europe/Paris" |
+| SERVER_OWNER_NAME | The name of the server owner. Will be used for emails personnalization and server identification (if you have multiple servers for example). | "Alexandre", "Jane", ... | "Numbus" |
+| SERVER_USER_EMAIL | This email will be used to send friendly alerts in case of problems. | "your-user@your-domain.com" |  |
+| SERVER_ADMIN_EMAIL | This email will be used to send complete alerts, including some logs, in case of problems. | "your-admin@your-domain.com" |  |
+| SERVER_AUTHORIZED_SSH_PUBKEYS | The public SSH key(s) that will be authorized to access the server. You can add multiple keys in the parenthesis, space-separated. | ( "ssh-ed25519 AAAAoefzefpoipoeCEZJCPEACPAcjapjcpajepcjAPJECJPEJAPJAZ yours@your-domain.com" ) |  |
@@ -0,0 +1,13 @@
+# Documentation
+
+## ⛏️ Configuring Crafty Controller
+
+To access your Minecraft server, **ports** need to be **open on the firewall**. In order to **minimize** the number of open ports and thus reduce **risks**, the numbus-server will only open a necessary number of ports that matches the number of minecraft. **Most people** should set the number of servers to **1** of their favorite version.
+
+These option **only configure networking** and **won't** create the Minecraft server for you. You will have to do it in Crafty's interface.
+
+| Variable | Description | Values | Default |
+| -------- | ----------- | ------ | --------- |
+| DYNMAP_ENABLED | Enables the Dynmap feature for Minecraft servers. | "true" or "false" | "false" |
+| WANTED_NUMBER_OF_JAVA_MINECRAFT_SERVERS | The number of Java Edition Minecraft servers you plan on creating. | "0", "1", ..., "100" | "0" |
+| WANTED_NUMBER_OF_BEDROCK_MINECRAFT_SERVERS | The number of Bedrock Edition Minecraft servers you plan on creating. | "0", "1", ..., "100" | "0" |
@@ -0,0 +1,45 @@
+# Documentation
+
+## 🛠️ Configuring the server's services
+
+| Variable | Description | Values | Default |
+| -------- | ----------- | ------ | --------- | 
+| SELECTED_DNS_SERVICE | The DNS service to install (AdBlocking). | ( "pi-hole" ), ( "adguard" ) | ( "pi-hole" ) |
+| SELECTED_WEB_APPLICATIONS | The list of web applications to install. | ( "nextcloud" ), ( "homepage" jellyfin" "it-tools" "netbootxyz" ), ... [see the full list below](./index.md#web-applications-list) |  |
+| SELECTED_SYSTEM_SERVICES | The list of system services to install. | ( "clamav" ), ( "virtualization" "clamav" ), ... [see the full list below](./index.md#system-services-list) |  |
+| SELECTED_DNS_SERVICE_SUBDOMAIN | Custom subdomain for the DNS service. | "my-dns" | Will be the name of the service. I.e. pi-hole.your-domain.com or adguard.your-domain.com |
+| SELECTED_WEB_APPLICATIONS_SUBDOMAIN | Custom subdomains for the web applications (must match the order of SELECTED_WEB_APPLICATIONS). | "my-cloud", "my-photos" | Will be the name of the service. I.e. nextcloud.your-domain.com, immich.your-domain.com, ... |
+
+## Web applications list
+
+This is the list of **all the available apps** that can be enabled on the numbus-server. You can choose as many as you want, just **keep in mind** that enabling more apps will be more resource **intensive** and consume more power.
+
+| Name | Description | Additional settings ? |
+| -------- | ----------- | ------ |
+| pi-hole | Simple, fully open network-wide Ad Blocker. | No |
+| adguard | Feature-rich network-wide Ad Blocker. | No |
+| crafty | Minecraft server(s) manager. | [Yes](./crafty.md) |
+| frigate | NVR with real-time local object detection. | No |
+| gitea | Painless self-hosted Git service. | No |
+| home-assistant | Open source home automation. | No |
+| homepage | A modern, secure, highly customizable dashboard. | No |
+| immich | High performance self-hosted photo/video management. | No |
+| it-tools | Collection of online tools for developers. | No |
+| jellyfin | The Free Software Media System. | No |
+| n8n | Workflow automation tool. | No |
+| netbootxyz | Network boot operating system installers. | No |
+| nextcloud | Self-hosted collaboration platform. | No |
+| ntfy | Send push notifications via HTTP. | No |
+| odoo | Open Source ERP and CRM. | No |
+| passbolt | Open source password manager. | No |
+| uptime-kuma | Self-hosted monitoring tool. | No |
+| vscodium | VS Code in your browser. | No |
+| clamav | Open-source anti-virus. | No |
+| virtualization | Run Virtual Machines (KVM/QEMU). | No |
+
+## System services list
+
+| Name | Description | Additional settings ? |
+| -------- | ----------- | ------ |
+| clamav | Open-source anti-virus software. | No |
+| virtualization | Run Virtual Machines (KVM/QEMU). | No |
@@ -0,0 +1,31 @@
+# Requirements
+
+### To deploy
+
+To deploy a numbus-backup-server, you will need :
+
+* A **live NixOS** bootable USB disk.
+
+You will make the **target** machine **boot** into the NixOS live environment using this **USB stick**. Download the [NixOS iso](https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso) image.
+
+*On Linux* : Flash it using [Impression (flatpak)](https://flathub.org/en/apps/io.gitlab.adhami3310.Impression) or [BalenaEtcher (AppImage)](https://etcher.balena.io/#download-etcher).
+
+*On MacOS* : Flash it using [BalenaEtcher](https://etcher.balena.io/#download-etcher).
+
+*On Windows* : Flash it using [Rufus](https://rufus.ie/en/#download) or [BalenaEtcher](https://etcher.balena.io/#download-etcher).
+
+* **Source** Machine:
+
+Can be any machine with **Nix installed**, e.g. a **NixOS** machine.
+
+* **Target** Machine:
+
+Can be **any computer** (desktop, SFF, tiny/mini/micro, even a laptop). It could be a dedicated server that you bought or just some computer that you decided to repurpose into a backup server.
+
+* **Network connection** between the source and the target machine.
+
+---
+
+### Next step
+
+[Configuration](./configuration/index.md)
@@ -0,0 +1,31 @@
+# Requirements
+
+### To deploy
+
+To deploy a numbus-backup-server, you will need :
+
+* A **live NixOS** bootable USB disk.
+
+You will make the **target** machine **boot** into the NixOS live environment using this **USB stick**. Download the [NixOS iso](https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso) image.
+
+*On Linux* : Flash it using [Impression (flatpak)](https://flathub.org/en/apps/io.gitlab.adhami3310.Impression) or [BalenaEtcher (AppImage)](https://etcher.balena.io/#download-etcher).
+
+*On MacOS* : Flash it using [BalenaEtcher](https://etcher.balena.io/#download-etcher).
+
+*On Windows* : Flash it using [Rufus](https://rufus.ie/en/#download) or [BalenaEtcher](https://etcher.balena.io/#download-etcher).
+
+* **Source** Machine:
+
+Can be any machine with **Nix installed**, e.g. a **NixOS** machine.
+
+* **Target** Machine:
+
+Can be **any computer** (desktop, SFF, tiny/mini/micro, even a laptop). It could be a dedicated server that you bought or just some computer that you decided to repurpose into a backup server.
+
+* **Network connection** between the source and the target machine.
+
+---
+
+### Next step
+
+[Configuration](./configuration/index.md)