root/the_prg_server_configuration_old
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation title page with clearer module links, formatting, and updated instructions
All checks were successful
Build Nix modules (dry-run) / build-modules (push) Successful in 3m59s
Details

Browse source
This commit is contained in:
Root User 2026-02-17 10:05:31 +01:00
parent 1095f9204a
commit 60d61faf25
Signed by: root
GPG key ID: 087F0A95E5766D72
1 changed files with 36 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

54
documentation_titlepage.md
View file

@ -1,4 +1,4 @@
# Welcome to the Polyteknisk Radiogruppe's Server Documentation
# Welcome to the Polytekni sk Radiogruppe's Server Documentation
This documentation outlines how the server is built and maintained, covering both short- and long-term management practices.
@ -11,7 +11,7 @@ This documentation outlines how the server is built and maintained, covering bot
As this document is in alpha release, the following package has been made with the standard Rust project template in the case
of having to create custom binaries for the system of the sysadmin or any related responsibilites/positions. Thusly,
the following document focus should be in the `nix-system-configs` folder, which
the following document focus should be in the *[nix-system-configs](nix-system-configs)* folder, which
is the main folder for the system configuration files and scripts.
> [!TIP]
@ -47,7 +47,7 @@ is the main folder for the system configuration files and scripts.
## Module Architecture
The system is organized into reusable modules across all NixOS machines in the PRG network.
The `system` module serves as the core configuration for Linux systems running on Proxmox, while supporting diverse
The *[system](nix-system-configs/modules/system)* module serves as the core configuration for Linux systems running on Proxmox, while supporting diverse
deployments through modular composition.
### Configuration Pattern
@ -58,15 +58,15 @@ This file demonstrates the standard pattern of declaring system variables using
### Core Modules
The `imports = [ ... ]` block specifies which modules are attached to your system configuration. These core modules ensure consistency and functionality:
- Bootloader [`bootloader`] (**required**): Handles system boot initialization. Configuration varies by installation type (ISO-assigned or Proxmox-assigned).
- Local [`local`] (**required**): Provides internet connectivity, hostname resolution, DNS configuration, and user settings.
- Standard Toolset [`lix-default.nix`] (**strongly recommended**): Ensures consistent tools across the PRG network—file transfers (rsync), SSH with key-based authentication, security features (U2F and SSH agent passwordless sudo), package management, and automated daily system upgrades.
- Desktop/Window Manager [`desktop-manager`] (**optional**): Simplifies VM interaction within Proxmox and supports systems requiring graphical interfaces.
- Toolsets [`toolsets`] (**optional**): Contains reusable configurations for specific tools or services that may be needed across multiple systems, such as remote building configurations.
- Secrets Config [`secrets-config`] (**required when needing password management**): Manages sensitive information like database credentials and Traefik secrets using SOPS-encrypted Nix files (see [this](https://github.com/Mic92/sops-nix) and [that](https://github.com/getsops/sops#2usage)). This module is essential for systems that require secure handling of secrets.
- Docker Containers [`songsheet`] (**optional**): This special module handles Docker Compose files that are converted to Nix. Currently it is used for a single VM but can be expanded to contain all [compose2nix](https://github.com/aksiksi/compose2nix) generated configurations.
- System Scripts [`system_scripts`] (**variable**): `system_scripts` contains scripts (for example, database backup scripts) that are often easier to write and maintain in shell than in Nix.
- Styling Scripts [`styling`] (**optional**): Contains styling assets such as .css themes, logo image files and fonts. This module is not required for system functionality but helps to have assets organized in one place and access later on.
- Bootloader - [bootloader](nix-system-configs/modules/bootloader) (**required**): Handles system boot initialization. Configuration varies by installation type (ISO-assigned or Proxmox-assigned).
- Local - [local](nix-system-configs/modules/local) (**required**): Provides internet connectivity, hostname resolution, DNS configuration, and user settings.
- Standard Toolset - [lix-default.nix](nix-system-configs/modules/lix-default.nix) (**strongly recommended**): Ensures consistent tools across the PRG network—file transfers (rsync), SSH with key-based authentication, security features (U2F and SSH agent passwordless sudo), package management, and automated daily system upgrades.
- Desktop/Window Manager - [desktop-manager](nix-system-configs/modules/desktop-manager) (**optional**): Simplifies VM interaction within Proxmox and supports systems requiring graphical interfaces.
- Toolsets - [toolsets](nix-system-configs/modules/toolsets) (**optional**): Contains reusable configurations for specific tools or services that may be needed across multiple systems, such as remote building configurations.
- Secrets Config [secrets-config](nix-system-configs/modules/secrets-config) (**required when needing password management**): Manages sensitive information like database credentials and Traefik secrets using SOPS-encrypted Nix files (see [this](https://github.com/Mic92/sops-nix) and [that](https://github.com/getsops/sops#2usage)). This module is essential for systems that require secure handling of secrets.
- Docker Containers - [songsheet](nix-system-configs/modules/songsheet) (**optional**): This special module handles Docker Compose files that are converted to Nix. Currently it is used for a single VM but can be expanded to contain all [compose2nix](https://github.com/aksiksi/compose2nix) generated configurations.
- System Scripts - [system_scripts](nix-system-configs/modules/system_scripts) (**variable**): `system_scripts` contains scripts (for example, database backup scripts) that are often easier to write and maintain in shell than in Nix.
- Styling Scripts - [styling](nix-system-configs/modules/styling) (**optional**): Contains styling assets such as .css themes, logo image files and fonts. This module is not required for system functionality but helps to have assets organized in one place and access later on.
### Module Organization
@ -122,7 +122,7 @@ The `imports = [ ... ]` block specifies which modules are attached to your syste
### Module Scripts
> [!INFO]
> [!WARNING]
> As you saw the odd one in the file structure, the `scripts` folder contains helper scripts to
> simplify maintenance and to make updating system configuration files on remote machines easier.
> These helper scripts live under `nix-system-configs/modules/scripts`.
@ -172,7 +172,7 @@ To add a new system configuration to the infrastructure:
};
```
3. **Register in `flake.nix`** to make it available for builds:
3. **Register in *[flake.nix](flake.nix)*** to make it available for builds:
```nix
nixosConfigurations = {
# ...existing configurations...
@ -183,12 +183,30 @@ To add a new system configuration to the infrastructure:
};
};
```
4. ***IF YOU WANT TO CHECK IT MANUALLY*** - **Test the configuration** before deploying, change the `nixos-your-system` accordingly:
```bash
nix build .#nixosConfigurations.nixos-your-system.config.system.build.toplevel
4. **Update the [dry_run.zsh](dry_run.zsh) script** according to variable name in the `flake.nix`
```zsh
configs=(
"nixos-local-wireguard-server"
"nixos-blank"
...
"nixos-your-system"
)
```
Once the build succeeds, the configuration is ready for deployment using the `pull.zsh` script on the target machine.
> [!TIP]
> ***IF YOU WANT TO CHECK IT MANUALLY*** - **Test the configuration** before deploying, change the `nixos-your-system` accordingly:
> ```zsh
> nix build .#nixosConfigurations.nixos-your-system.config.system.build.toplevel
> ```
> Or if you have already setup the `dry_run.zsh`
> ```zsh
> zsh dry-run.zsh nixos-your-system
> ```
Once the build succeeds by running the `zsh dry_run.zsh` or by looking at the Forgejo Actions of this repository, the configuration is ready for deployment using the `pull.zsh` script on the target machine.
## How to maintain the local machines