diff --git a/README.md b/README.md index 40cdbf9..3b82d1a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ ### Title +If you want to see proper documentation, please visit the [documentation](documentation_titlepage.md) page. + Hewo :3 - you have found the Polyteknisk Radiogruppe's NixOS configurations of our server, feel free to poke holes at it, as security through obscurity isn't really security. Like don't be a douche poking holes, but be nice, do not ruin it if you were on the other side, silliness is okay, but consent is best. diff --git a/documentation_titlepage.md b/documentation_titlepage.md new file mode 100644 index 0000000..ee020cf --- /dev/null +++ b/documentation_titlepage.md @@ -0,0 +1,199 @@ +# Welcome to the Polyteknisk Radiogruppe's Server Documentation + +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 + +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 +is the main folder for the system configuration files and scripts. + +> [!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 +├──  nginx +│ └──  matrix.conf +├──  nix-system-configs +│ ├──  build +│ │ └──  configuration.nix +│ ├──  christine-server_do_not_use.nix +│ ├──  database-deprecated +│ │ └──  configuration.nix +│ ├──  dns +│ │ ├──  configuration-knot.nix +│ │ ├──  configuration-pihole-green.nix +│ │ ├──  configuration-pihole-inside-system.nix +│ │ └──  configuration-pihole-orange.nix +│ ├──  example-composed.nix +│ ├──  forgejo-deprecated +│ │ ├──  forgejo-localconfig.nix +│ │ ├──  pull.zsh +│ │ └──  push.zsh +│ ├──  gateway +│ │ └──  gateway.nix +│ ├──  modules +│ │ ├──  bootloader +│ │ ├──  desktop-manager +│ │ ├──  lix-default.nix +│ │ ├──  local +│ │ ├──  scripts +│ │ ├──  secrets-config +│ │ ├──  songsheet +│ │ ├──  system +│ │ ├──  system_scripts +│ │ └──  toolsets +│ ├──  old-server-notes.md +│ ├──  prg-blank-setup +│ │ ├──  blank-proxmox-partition.nix +│ │ └──  example.nix +│ ├──  secrets +│ │ ├──  database +│ │ ├──  songsheet +│ │ └──  traefik +│ └──  traefik-deprecated +│ ├──  pull.zsh +│ ├──  push.zsh +│ └──  traefik-config.nix +├──  README.md +├──  sops-nix-readme.md +├── 󱧼 src +│ └──  main.rs +└──  target + ├──  CACHEDIR.TAG + └──  debug + ├──  build + ├──  deps + ├──  examples + └──  incremental +``` + +## 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 +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 +``` diff --git a/maintence_cheatsheet.md b/maintence_cheatsheet.md deleted file mode 100644 index f595040..0000000 --- a/maintence_cheatsheet.md +++ /dev/null @@ -1,4 +0,0 @@ -# Upload the config to the server -```zsh -rsync -avz --progress2 FILE root@HOSTNAME:/etc/nixos/configuration-knot.nix -``` \ No newline at end of file diff --git a/nix-system-configs/modules/scripts/compose_two_nix.zsh b/nix-system-configs/modules/scripts/compose_two_nix.zsh old mode 100644 new mode 100755 diff --git a/nix-system-configs/modules/scripts/pull.zsh b/nix-system-configs/modules/scripts/pull.zsh old mode 100644 new mode 100755 diff --git a/nix-system-configs/modules/scripts/push.zsh b/nix-system-configs/modules/scripts/push.zsh old mode 100644 new mode 100755 diff --git a/nix-system-configs/modules/system/blank_system_USE_THIS_AS_COPY.nix b/nix-system-configs/modules/system/blank_system_USE_THIS_AS_COPY.nix new file mode 100644 index 0000000..6fa22ea --- /dev/null +++ b/nix-system-configs/modules/system/blank_system_USE_THIS_AS_COPY.nix @@ -0,0 +1,49 @@ +{ + config, + pkgs, + lib, + ... +}: { + options.local = { + hostname = lib.mkOption { + type = lib.types.str; + default = "nixos-default"; + description = "System hostname"; + }; + username = lib.mkOption { + type = lib.types.str; + default = "user"; + description = "Primary user username"; + }; + userDescription = lib.mkOption { + type = lib.types.str; + default = "NixOS User"; + description = "Primary user description"; + }; + address = lib.mkOption { + type = lib.types.str; + default = "10.1.1.100"; + description = "Static IP address"; + }; + }; + + imports = [ + ./modules/desktop-manager/sway_greetd_homemanager.nix + ./modules/local/hostname_username.nix + ./modules/local/networking_local.nix + ./modules/bootloader/seabios-assigned-iso-at-birth.nix + ./modules/lix-default.nix + # Optionally to enable remote building: ./modules/toolsets/remote_building.nix + #./modules/songsheet/wavelog/docker-compose.nix + #./modules/secrets-config/sops-the-blank-system.nix + ]; + + config = { + local.hostname = "nixos-songsheet"; + local.username = "songsheetprg"; + local.userDescription = "NixOS PRG Portainer-Like Songsheet Service"; + local.address = "10.1.1.249"; + + system.stateVersion = "25.11"; + }; +} diff --git a/nix-system-configs/modules/system/teamspeak.nix b/nix-system-configs/modules/system/teamspeak.nix index 5b5ab6a..7427647 100644 --- a/nix-system-configs/modules/system/teamspeak.nix +++ b/nix-system-configs/modules/system/teamspeak.nix @@ -68,6 +68,10 @@ address = "0.0.0.0"; database_backend = "rocksdb"; server_name = "lgbtq.prg-radio.org"; + allow_federation = true; + allow_check_for_updates = true; + + trusted_servers = ["matrix.org"]; # See https://docs.conduit.rs/turn.html, and https://github.com/element-hq/synapse/blob/develop/docs/turn-howto.md for more details # turn_uris = [ @@ -82,11 +86,13 @@ 80 443 12244 + 8448 ]; networking.firewall.allowedUDPPorts = [ 80 443 12244 + 8448 ]; system.stateVersion = "25.11"; diff --git a/nix-system-configs/modules/system/traefik.nix b/nix-system-configs/modules/system/traefik.nix index ffe915e..3613882 100644 --- a/nix-system-configs/modules/system/traefik.nix +++ b/nix-system-configs/modules/system/traefik.nix @@ -48,7 +48,8 @@ staticConfigOptions = { entryPoints = { web = { - address = ":80"; + # Bind on IPv6 as well as IPv4 by using [::]:80 + address = "[::]:80"; asDefault = true; http.redirections.entrypoint = { to = "websecure"; @@ -56,7 +57,8 @@ }; }; websecure = { - address = ":443"; + # Bind on IPv6 as well as IPv4 by using [::]:443 + address = "[::]:443"; asDefault = true; http.tls = { domains = [ @@ -69,17 +71,19 @@ }; # Federation entrypoint: external TLS on 8448 federation = { - address = ":8448"; + # Bind on IPv6 as well as IPv4 by using [::]:8448 + address = "[::]:8448"; }; # TeamSpeak entry points teamspeak-voice = { - address = ":9987/udp"; + # UDP entrypoint bind to IPv6 as well + address = "[::]:9987/udp"; }; teamspeak-squery = { - address = ":10022/tcp"; + address = "[::]:10022/tcp"; }; teamspeak-data = { - address = ":30033/tcp"; + address = "[::]:30033/tcp"; }; }; log = { @@ -166,6 +170,23 @@ rule = "HostSNI(`*`)"; service = "matrix-federation"; entryPoints = ["federation"]; + # Pass TLS through to the backend (Conduit handles TLS on port 12244) + tls = { + passthrough = true; + }; + }; + # Also accept TLS passthrough on port 443 for the Matrix host so + # other servers that contact :443/_matrix/* + # will be forwarded to Conduit as well. + # I guess I had to declare the rule explicitly here again? + matrix-tls443 = { + # match by SNI to avoid interfering with other HTTPS sites + rule = "HostSNI(`lgbtq.prg-radio.org`)"; + service = "matrix-federation"; + entryPoints = ["websecure"]; + tls = { + passthrough = true; + }; }; };