Enhance documentation for server management and module architecture.
This commit is contained in:
parent
a986fe18c4
commit
aec8fc397b
GPG key ID:
087F0A95E5766D72
6 changed files with 139 additions and 50 deletions
|
|
@ -1,9 +1,11 @@
|
|||
# Welcome to the Polyteknisk Radiogruppe's Server Documentation
|
||||
|
||||
The following the documentation showcases how the server is built up and how one should manage this in both long and short terms.
|
||||
Also, thusly, this document should be actively maintained in the functional changes no matter how small or large, as in
|
||||
if a flag is changed in the compiliation of the system build, password key changes, new added standard package, then it must
|
||||
be documented here.
|
||||
This documentation outlines how the server is built and maintained, covering both short- and long-term management practices.
|
||||
|
||||
> [!NOTE]
|
||||
> **Important:** This document should be actively maintained whenever functional changes occur—no matter how small or large.
|
||||
> This includes compilation flag changes, password key updates, new standard packages, and any other modifications.
|
||||
|
||||
|
||||
## Documentation File Structure
|
||||
|
||||
|
|
@ -12,16 +14,24 @@ of having to create custom binaries for the system of the sysadmin or any relate
|
|||
the following document focus should be in the `nix-system-configs` folder, which
|
||||
is the main folder for the system configuration files and scripts.
|
||||
|
||||
>[note!] For the documentation maintainer, be sure to update this tree with the `lsd` package with running the `lsd --tree` of the project directory. Please do take care to not have some secrets exposed here in your own home system if so be it.
|
||||
> [!TIP] For documentation maintainers: Update the directory tree using `lsd --tree` from the project root. Be careful not to expose secrets and other things when documenting from your local system.
|
||||
|
||||
```bash
|
||||
.
|
||||
├── backup-key.private
|
||||
├── Cargo.lock
|
||||
├── Cargo.toml
|
||||
├── compose2nix-readme.md
|
||||
├── docker-compose.wellknown.override.yml
|
||||
├── documentation_titlepage.md
|
||||
├── dummy.txt
|
||||
├── LICENSE
|
||||
├── maintence_cheatsheet.md
|
||||
├── nginx
|
||||
│ └── matrix.conf
|
||||
├── nix-system-configs
|
||||
│ ├── build
|
||||
│ │ └── configuration.nix
|
||||
│ ├── christine-server_do_not_use.nix
|
||||
│ ├── database-deprecated
|
||||
│ │ └── configuration.nix
|
||||
│ ├── dns
|
||||
|
|
@ -38,71 +48,152 @@ is the main folder for the system configuration files and scripts.
|
|||
│ │ └── gateway.nix
|
||||
│ ├── modules
|
||||
│ │ ├── bootloader
|
||||
│ │ │ ├── seabios-assigned-iso-at-birth.nix
|
||||
│ │ │ └── seabios-assigned-proxmox-at-birth.nix
|
||||
│ │ ├── desktop-manager
|
||||
│ │ │ ├── gnome.nix
|
||||
│ │ │ └── sway_greetd_homemanager.nix
|
||||
│ │ ├── lix-default.nix
|
||||
│ │ ├── local
|
||||
│ │ │ ├── hostname_username.nix
|
||||
│ │ │ └── networking_local.nix
|
||||
│ │ ├── scripts
|
||||
│ │ │ ├── compose_two_nix.zsh
|
||||
│ │ │ ├── pull.zsh
|
||||
│ │ │ └── push.zsh
|
||||
│ │ ├── secrets-config
|
||||
│ │ │ ├── sops-composesongsheet.nix
|
||||
│ │ │ └── sops-database.nix
|
||||
│ │ ├── songsheet
|
||||
│ │ │ └── wavelog
|
||||
│ │ │ ├── docker-compose.nix
|
||||
│ │ │ ├── docker-compose.yml
|
||||
│ │ │ └── notes.md
|
||||
│ │ ├── system
|
||||
│ │ │ ├── compose-songsheet.nix
|
||||
│ │ │ ├── database.nix
|
||||
│ │ │ ├── forgejo.nix
|
||||
│ │ │ ├── teamspeak.nix
|
||||
│ │ │ └── traefik.nix
|
||||
│ │ ├── system_scripts
|
||||
│ │ │ ├── backup_strategem
|
||||
│ │ │ │ └── manual_database_restore.zsh
|
||||
│ │ │ └── gcloud_backup.nix
|
||||
│ │ └── toolsets
|
||||
│ │ └── remote_building.nix
|
||||
│ ├── old-server-notes.md
|
||||
│ ├── prg-blank-setup
|
||||
│ │ ├── blank-proxmox-partition.nix
|
||||
│ │ └── example.nix
|
||||
│ ├── secrets
|
||||
│ │ ├── database
|
||||
│ │ │ ├── gcloud_bucket.json
|
||||
│ │ │ └── secrets.yaml
|
||||
│ │ ├── songsheet
|
||||
│ │ │ ├── example.yaml
|
||||
│ │ │ └── secrets.yaml
|
||||
│ │ └── traefik
|
||||
│ │ └── test.yaml
|
||||
│ └── traefik-deprecated
|
||||
│ ├── pull.zsh
|
||||
│ ├── push.zsh
|
||||
│ └── traefik-config.nix
|
||||
├── README.md
|
||||
└── src
|
||||
└── main.rs
|
||||
├── sops-nix-readme.md
|
||||
├── src
|
||||
│ └── main.rs
|
||||
└── target
|
||||
├── CACHEDIR.TAG
|
||||
└── debug
|
||||
├── build
|
||||
├── deps
|
||||
├── examples
|
||||
└── incremental
|
||||
```
|
||||
|
||||
As you can see it, the main system is separated up the the following `modules`, where all Nix configurations are thusly reused and
|
||||
updated across different systems. As mentioned before, `system` is the start of the core configuration of the following linux systems running in Proxmox.
|
||||
Looking at the `blank_system_USE_THIS_AS_COPY.nix`, you can see that the system is variables are declared dynamically in Nix-like variable declaration where
|
||||
we create the local new options class and make this callable in the other functions in the imports. Speaking of imports, `imports = [ ... ] ` block shows
|
||||
which modules which are then attached the core system, usually the bootloader is a must feature to the attached as the following system will not boot properly without it but different systems, depending how they were installed, need different configurations.
|
||||
Then usually the networking module is also attached to have capabilities to use networking i.e. internet access, hostname, which DNS to use etc. `lix-default.nix` module imported is the
|
||||
the assumed standard which tools each NixOS machine in the PRG network has, which is important for ensuring consistent existence of the tools used and maintanence within the machine outside of this documentation and machine buildings, as in enabling file transfers, package manager, SSH, password management, locales, timezones, upgrade system schedules.
|
||||
Next piece that should be added is the desktop/window management which could help simplifing the interaction of the VMs in the Proxmox or other external systems that are depednent of this repository.
|
||||
## Module Architecture
|
||||
|
||||
As you can see that each aformentioned module in specific tasks are in their folders `local` for networking and users, `desktop-manager` for interaction, `bootloader` for... well.. bootloaders etc. Feel free to add more different modules for each system need or change.
|
||||
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
|
||||
deployments through modular composition.
|
||||
|
||||
### Configuration Pattern
|
||||
|
||||
Use `blank_system_USE_THIS_AS_COPY.nix` as a template for new system configurations.
|
||||
This file demonstrates the standard pattern of declaring system variables using Nix syntax to create custom local options that are callable across imported modules.
|
||||
|
||||
### 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.
|
||||
|
||||
### Module Organization
|
||||
|
||||
```bash
|
||||
.
|
||||
├── bootloader
|
||||
│ ├── seabios-assigned-iso-at-birth.nix
|
||||
│ └── seabios-assigned-proxmox-at-birth.nix
|
||||
├── desktop-manager
|
||||
│ ├── gnome.nix
|
||||
│ └── sway_greetd_homemanager.nix
|
||||
├── lix-default.nix
|
||||
├── local
|
||||
│ ├── hostname_username.nix
|
||||
│ └── networking_local.nix
|
||||
├── scripts
|
||||
│ ├── compose_two_nix.zsh
|
||||
│ ├── pull.zsh
|
||||
│ └── push.zsh
|
||||
├── secrets-config
|
||||
│ ├── sops-composesongsheet.nix
|
||||
│ └── sops-database.nix
|
||||
├── songsheet
|
||||
│ └── wavelog
|
||||
├── system
|
||||
│ ├── blank_system_USE_THIS_AS_COPY.nix
|
||||
│ ├── compose-songsheet.nix
|
||||
│ ├── database.nix
|
||||
│ ├── forgejo.nix
|
||||
│ ├── teamspeak.nix
|
||||
│ └── traefik.nix
|
||||
├── system_scripts
|
||||
│ ├── backup_strategem
|
||||
│ └── gcloud_backup.nix
|
||||
└── toolsets
|
||||
└── remote_building.nix
|
||||
```
|
||||
|
||||
### Module Scripts
|
||||
|
||||
> [!INFO] 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`.
|
||||
|
||||
#### `pull.zsh`
|
||||
|
||||
Deploys configuration changes from the repository to the local system. This script:
|
||||
|
||||
1. Prompts you to select a system configuration (or accepts one as a command-line argument)
|
||||
2. Pulls the latest changes from the git repository
|
||||
3. Syncs the `modules` directory to `/etc/nixos/modules`
|
||||
4. Syncs the `secrets` directory to `/etc/nixos/secrets` (if present)
|
||||
5. Syncs the `system_scripts` directory to `/etc/nixos/system_scripts` (if present)
|
||||
6. Copies the selected system configuration to `/etc/nixos/configuration.nix`
|
||||
7. Executes `nixos-rebuild switch --upgrade-all` to apply changes
|
||||
|
||||
#### `push.zsh`
|
||||
|
||||
Synchronizes local system changes back to the repository. This script:
|
||||
|
||||
1. Prompts you to select a system configuration (or accepts one as a command-line argument)
|
||||
2. Rebuilds the local NixOS system with `nixos-rebuild switch --upgrade-all`
|
||||
3. Pulls the latest changes from the git repository
|
||||
4. Copies the active configuration from `/etc/nixos/configuration.nix` back to the repository
|
||||
5. Syncs changes from `/etc/nixos/modules` back to the repository
|
||||
6. Stages, commits, and pushes changes to the remote git repository with a timestamped commit message
|
||||
|
||||
## How to maintain the local machines
|
||||
|
||||
> [!NOTE] The following maintenance scripts should be made less unwieldy to use, so they will be changed in the next
|
||||
> possible project restructuring.
|
||||
|
||||
From the home machine:
|
||||
|
||||
The remote access IP address should be reachable via the VPN service you use (Tailscale, OpenVPN, etc.).
|
||||
To connect to the remote machine (or other machines on the same network) with established keys, use:
|
||||
```zsh
|
||||
ssh -A REMOTE_MACHINE_USERNAME@ACCESS_IP_ADDRESS
|
||||
```
|
||||
To connect to other machines:
|
||||
```zsh
|
||||
ssh -A OTHER_REMOTE_MACHINE_USERNAME@LOCAL_IP_ADDRESS
|
||||
```
|
||||
|
||||
After having had connected to the remote machine, run the following commands, although this assumes you have git cloned
|
||||
this repository into the home directory of the remote machine. Now, running through the selection of the different
|
||||
systems as per script and upon selection of the script, it will then try to upgrade the system.
|
||||
|
||||
```zsh
|
||||
cd the-prg-server-structure
|
||||
git pull
|
||||
zsh nix-system-configs/modules/scripts/pull.zsh
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue