From 5ec78f03d32c549e4a1c5ec54f90f6250b39bbc2 Mon Sep 17 00:00:00 2001 From: Christine Elisabeth Koppel Date: Tue, 17 Feb 2026 09:32:39 +0100 Subject: [PATCH] Update documentation title page. --- documentation_titlepage.md | 86 +++++++++++++++----------------------- 1 file changed, 34 insertions(+), 52 deletions(-) diff --git a/documentation_titlepage.md b/documentation_titlepage.md index eb7dbd6..4e05d5d 100644 --- a/documentation_titlepage.md +++ b/documentation_titlepage.md @@ -14,72 +14,34 @@ 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. -> [!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. +> [!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 +├──  dry_run.zsh +├──  flake.lock +├──  flake.nix ├──  LICENSE -├──  nginx -│ └──  matrix.conf ├──  nix-system-configs -│ ├──  build -│ │ └──  configuration.nix -│ ├──  christine-server_do_not_use.nix +│ ├──  build-deprecated │ ├──  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 +├──  secrets.md +└── 󱧼 src + └──  main.rs ``` ## Module Architecture @@ -104,6 +66,7 @@ The `imports = [ ... ]` block specifies which modules are attached to your syste - 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. ### Module Organization @@ -124,27 +87,43 @@ The `imports = [ ... ]` block specifies which modules are attached to your syste │ ├──  pull.zsh │ └──  push.zsh ├──  secrets-config +│ ├──  notes.md +│ ├──  sops-build-machine.nix │ ├──  sops-composesongsheet.nix -│ └──  sops-database.nix +│ ├──  sops-database.nix +│ ├──  sops-mail.nix +│ └──  sops-wireguard.nix ├──  songsheet │ └──  wavelog +├──  styling +│ ├──  forgejo +│ ├──  PRG_logo.png +│ └──  PRG_logo.svg ├──  system │ ├──  blank_system_USE_THIS_AS_COPY.nix +│ ├──  build_machine.nix │ ├──  compose-songsheet.nix │ ├──  database.nix │ ├──  forgejo.nix +│ ├──  gramethus.nix +│ ├──  mail-server.nix +│ ├──  system_wishlist.md │ ├──  teamspeak.nix -│ └──  traefik.nix +│ ├──  traefik.nix +│ └──  wireguard_server.nix ├──  system_scripts │ ├──  backup_strategem │ └──  gcloud_backup.nix └──  toolsets -└──  remote_building.nix + ├──  grafana_metric.nix + ├──  remote_building.nix + └──  wireguard_peer.nix ``` ### Module Scripts -> [!INFO] As you saw the odd one in the file structure, the `scripts` folder contains helper scripts to +> [!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`. @@ -213,16 +192,19 @@ Once the build succeeds, the configuration is ready for deployment using the `pu ## 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 +> [!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