From 170bd14a344d92f3b5fd0979192733ebea319cdb Mon Sep 17 00:00:00 2001 From: naturallaw77 Date: Sat, 23 May 2026 11:28:02 -0500 Subject: [PATCH 1/4] update readme --- README.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 167 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a93f5ec..30d8bdb 100644 --- a/README.md +++ b/README.md @@ -1 +1,167 @@ -### Testing Branch +
+ +Sovran Systems + +# Sovran_SystemsOS — Internal Mirror + +Private development mirror of **Sovran_SystemsOS**. +Canonical source lives on Gitea — this repo is for internal work only. + +`Base Development` · NixOS Flake · AGPL-3.0 + +[Canonical source (Gitea)](https://git.sovransystems.com/Sovran_Systems/Sovran_SystemsOS) · [Public site](https://sovransystems.com) + +
+ +--- + +> **Heads up:** This repo is private. End users never see it. Public docs, build instructions, and marketing copy live on the website and on Gitea — do not duplicate them here. This README is for maintainers. + +## Table of Contents + +1. [What This Repo Is](#what-this-repo-is) +2. [Architecture](#architecture) +3. [Module Catalog](#module-catalog) +4. [The Three Modes (internal reference)](#the-three-modes-internal-reference) +5. [Build & Deploy Reference](#build--deploy-reference) +6. [Networking & Reverse Proxy](#networking--reverse-proxy) +7. [Security Posture](#security-posture) +8. [Backups & Recovery](#backups--recovery) +9. [License](#license) + +--- + +## What This Repo Is + +Sovran_SystemsOS is defined entirely as a **Nix flake** (`flake.nix`) and built from source. There is no pre-built binary — the System Installer is produced from this tree. Everything the system runs is traceable to a `.nix` file in this repo, pinned by `flake.lock`. + +The control center is the **Hub** — a built-in panel that lets the operator launch, monitor, and toggle services without touching a terminal. Under the hood, the Hub writes to `custom.nix`, which is just a normal Nix module. + +## Architecture + +``` + ┌─────────────────────────┐ + │ flake.nix │ + │ inputs: nixpkgs, │ + │ nix-bitcoin, nixvim, │ + │ btc-clients, bip110 │ + └───────────┬─────────────┘ + │ nixosModules.Sovran_SystemsOS + ▼ + ┌──────────────────────────┐ imports ┌──────────────────────────┐ + │ configuration.nix │────────────▶│ modules/modules.nix │ + │ boot / fs / users / │ │ core/* + services + opt │ + │ desktop / nix settings │ │ features │ + └──────────────────────────┘ └──────────┬───────────────┘ + ▲ │ + │ ./role-state.nix (mode/role) ▼ + │ ./custom.nix (user overrides) ┌────────────────────┐ + │ │ modules/*.nix │ + └───────── sovran-hub writes ───────▶│ synapse / wordpress│ + │ nextcloud / etc. │ + └────────────────────┘ +``` + +- **`flake.nix`** declares two NixOS configurations: + - `nixosConfigurations.nixos` — the running system. + - `nixosConfigurations.sovran_systemsos-iso` — the System Installer. +- **`configuration.nix`** owns host concerns (boot, filesystems, users, desktop, locale, Nix settings, firewall, audio, backups). +- **`modules/modules.nix`** is the service router. Every other module is opt-in via flags read from `role-state.nix` and `custom.nix`. + +## Module Catalog + +Defaults follow the import order in `modules/modules.nix`. Toggles live in `custom.nix` (the Hub writes them) and `role-state.nix`. + +| Module | Default | Purpose | +|---|---|---| +| `core/*` | **on** | Roles, Caddy, Njalla, Hub, desktop, perf, ssh-bootstrap | +| `php.nix`, `credentials.nix` | **on** | Required by web services & secrets | +| `synapse.nix` | **on** | Matrix homeserver | +| `wordpress.nix` | **on** | WordPress + PHP-FPM vhost | +| `nextcloud.nix` | **on** | Files / calendar / contacts | +| `vaultwarden.nix` | **on** | Bitwarden-compatible secrets vault | +| `bitcoinecosystem.nix` | **on** | bitcoind/electrs/LND/RTL/BTCPay (over Tor) | +| `wallet-autoconnect.nix` | **on** | Sparrow/Bisq ↔ node handshake | +| `haven.nix` | off | Nostr relay | +| `bip110.nix` | off | Bitcoin Knots BIP-110 | +| `element-calling.nix` | off | LiveKit + JWT for E2E calling | +| `mempool.nix` | off | Mempool.space dashboard | +| `bitcoin-core.nix` | off | Standalone bitcoind | +| `rdp.nix` | off | xrdp remote desktop | +| `sshd.nix` | off | Public-facing OpenSSH | + +> Tor is wired directly into the Bitcoin stack. In `modules/bitcoinecosystem.nix`, `bitcoind`, `electrs`, and `lnd` all set `tor.enforce = true` and `tor.proxy = true`, and onion services are exposed for `bitcoind`, `electrs`, `lnd`, and `rtl` via `nix-bitcoin.onionServices.*`. + +## The Three Modes (internal reference) + +Selected by `role-state.nix`, resolved by `modules/core/role-logic.nix`. All three configurations are produced from this same flake. + +| Mode | What's enabled on top of the base NixOS + GNOME | +|---|---| +| **Desktop** | Private daily-driver. Sparrow + Bisq included. | +| **Node** | Desktop + full Bitcoin stack (bitcoind/electrs/LND/RTL/BTCPay over Tor). | +| **Server+Desktop** | Node + self-hosting services (Synapse, Nextcloud, WordPress, Vaultwarden, Element Calling, etc.). | + +## Build & Deploy Reference + +Internal commands. Run from the flake root. + +| Action | Command | +|---|---| +| Build the System Installer | `nix build .#nixosConfigurations.sovran_systemsos-iso.config.system.build.isoImage` | +| Switch now | `sudo nixos-rebuild switch --flake .#nixos` | +| Test in current boot only | `sudo nixos-rebuild test --flake .#nixos` | +| Stage for next boot | `sudo nixos-rebuild boot --flake .#nixos` | +| Build only (no activation) | `nixos-rebuild build --flake .#nixos` | +| Update pinned inputs | `nix flake update` (then rebuild) | +| Rollback last switch | `sudo nixos-rebuild switch --rollback` | +| Garbage-collect (>7 days) | Automatic weekly; manual: `sudo nix-collect-garbage -d` | + +## Networking & Reverse Proxy + +- **Firewall on by default** (`networking.firewall.enable = true`). The only port opened at host level is **UDP 5353** for mDNS (Avahi). Every other port is opened by the module that needs it. +- **Caddy** (`modules/core/caddy.nix`) terminates TLS for all HTTP services. Operator vhosts go through `sovran_systemsOS.caddy.extraVirtualHosts`. +- **Njalla** dynamic DNS (`modules/core/njalla.nix`) keeps records in sync via a 15-minute cron job. +- **Avahi** publishes `sovransystemsos.local` on the LAN. +- **Tor** is enabled with `torsocks` available. The Bitcoin stack uses it directly — see [Security Posture](#security-posture). +- **SSH:** localhost-only by default (`core/sshd-localhost.nix`). Public OpenSSH is opt-in (`modules/sshd.nix`). + +## Security Posture + +Facts about the defaults, straight from `configuration.nix` and the modules: + +- **Reproducible builds.** Every artifact derives from `flake.lock`. The same commit produces the same OS. +- **Bitcoin stack over Tor.** In `modules/bitcoinecosystem.nix`, `bitcoind`, `electrs`, and `lnd` all set `tor.enforce = true`, and onion services are exposed for `bitcoind`, `electrs`, `lnd`, and `rtl`. +- **Firewall on, public sshd off, RDP off, auto-login off.** +- **EFI** is mounted with `umask=0077`. +- **Kernel surface trimmed.** `boot.blacklistedKernelModules = [ "rxrpc" ];` +- **Emergency mode disabled** (`systemd.enableEmergencyMode = false`). +- **GNOME Keyring** wired into PAM (`gdm-password`, `gdm-autologin`); the keyring file is declaratively created with `0600` perms via `systemd.tmpfiles`. +- **PostgreSQL** is local-only (`local trust`, `127.0.0.1/32 trust`, `::1/128 trust`). Not exposed to the network. +- **Secrets** are materialized through `modules/credentials.nix` and `nix-bitcoin-secrets` (`/etc/nix-bitcoin-secrets/`, included in backups). +- **Weekly garbage collection** with `--delete-older-than 7d`. + +## Backups & Recovery + +`services.rsnapshot` snapshots hourly and daily to `/run/media/Second_Drive/BTCEcoandBackup/NixOS_Snapshot_Backup`: + +``` +backup /home/ localhost/ +backup /var/lib/ localhost/ +backup /etc/nixos/ localhost/ +backup /etc/nix-bitcoin-secrets/ localhost/ +retain hourly 5 +retain daily 5 +cron hourly 0 * * * * +cron daily 50 21 * * * +``` + +The second drive is mounted by label (`BTCEcoandBackup`) with `nofail` so a missing drive doesn't block boot. + +## License + +Licensed under the **GNU Affero General Public License v3.0** — see [`LICENSE`](./LICENSE). + +--- + +Internal mirror. Public copy lives on Gitea. -- 2.54.0 From 31cb48cc2b1cc01c65979142a2c083fc4771ea28 Mon Sep 17 00:00:00 2001 From: Sovran Systems <99053422+naturallaw777@users.noreply.github.com> Date: Sat, 23 May 2026 11:30:45 -0500 Subject: [PATCH 2/4] Add new Sovran Hub icon (v3) --- assets/sovran-hub-icon.svg | 52 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 assets/sovran-hub-icon.svg diff --git a/assets/sovran-hub-icon.svg b/assets/sovran-hub-icon.svg new file mode 100644 index 0000000..66d6123 --- /dev/null +++ b/assets/sovran-hub-icon.svg @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- 2.54.0 From aa69d40f080c22a2688caa57a06c0d056b004ce3 Mon Sep 17 00:00:00 2001 From: Sovran Systems <99053422+naturallaw777@users.noreply.github.com> Date: Sat, 23 May 2026 11:33:46 -0500 Subject: [PATCH 3/4] README: use new Sovran Hub icon --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 30d8bdb..2ae20a9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-Sovran Systems +Sovran Systems # Sovran_SystemsOS — Internal Mirror @@ -15,7 +15,7 @@ Canonical source lives on Gitea — this repo is for internal work only. --- -> **Heads up:** This repo is private. End users never see it. Public docs, build instructions, and marketing copy live on the website and on Gitea — do not duplicate them here. This README is for maintainers. +> **Heads up:** This repo is private. End users never see it. Public docs, build instructions, and marketing copy live on the website and on Gitea — do not duplicate them here. This README is for internal contributors. ## Table of Contents @@ -33,9 +33,9 @@ Canonical source lives on Gitea — this repo is for internal work only. ## What This Repo Is -Sovran_SystemsOS is defined entirely as a **Nix flake** (`flake.nix`) and built from source. There is no pre-built binary — the System Installer is produced from this tree. Everything the system runs is traceable to a `.nix` file in this repo, pinned by `flake.lock`. +Sovran_SystemsOS is defined entirely as a **Nix flake** (`flake.nix`) and built from source. There is no pre-built binary — the System Installer is produced from this tree. Everything the system does is declared here. -The control center is the **Hub** — a built-in panel that lets the operator launch, monitor, and toggle services without touching a terminal. Under the hood, the Hub writes to `custom.nix`, which is just a normal Nix module. +The control center is the **Hub** — a built-in panel that lets the operator launch, monitor, and toggle services without touching a terminal. Under the hood, the Hub writes to `custom.nix`, which feeds back into the flake. ## Architecture @@ -90,7 +90,7 @@ Defaults follow the import order in `modules/modules.nix`. Toggles live in `cust | `rdp.nix` | off | xrdp remote desktop | | `sshd.nix` | off | Public-facing OpenSSH | -> Tor is wired directly into the Bitcoin stack. In `modules/bitcoinecosystem.nix`, `bitcoind`, `electrs`, and `lnd` all set `tor.enforce = true` and `tor.proxy = true`, and onion services are exposed for `bitcoind`, `electrs`, `lnd`, and `rtl` via `nix-bitcoin.onionServices.*`. +> Tor is wired directly into the Bitcoin stack. In `modules/bitcoinecosystem.nix`, `bitcoind`, `electrs`, and `lnd` all set `tor.enforce = true` and `tor.proxy = true`, and onion services are exposed for them. ## The Three Modes (internal reference) @@ -131,7 +131,7 @@ Internal commands. Run from the flake root. Facts about the defaults, straight from `configuration.nix` and the modules: - **Reproducible builds.** Every artifact derives from `flake.lock`. The same commit produces the same OS. -- **Bitcoin stack over Tor.** In `modules/bitcoinecosystem.nix`, `bitcoind`, `electrs`, and `lnd` all set `tor.enforce = true`, and onion services are exposed for `bitcoind`, `electrs`, `lnd`, and `rtl`. +- **Bitcoin stack over Tor.** In `modules/bitcoinecosystem.nix`, `bitcoind`, `electrs`, and `lnd` all set `tor.enforce = true`, and onion services are exposed for `bitcoind`, `electrs`, `lnd`, and friends. - **Firewall on, public sshd off, RDP off, auto-login off.** - **EFI** is mounted with `umask=0077`. - **Kernel surface trimmed.** `boot.blacklistedKernelModules = [ "rxrpc" ];` -- 2.54.0 From 2388039b630dde7cd4d47608927ad611a95d7476 Mon Sep 17 00:00:00 2001 From: Sovran Systems <99053422+naturallaw777@users.noreply.github.com> Date: Sat, 23 May 2026 11:35:09 -0500 Subject: [PATCH 4/4] Add Sovran Hub icon SVG referenced by README --- iso/assets/sovran-hub-icon.svg | 52 ++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 iso/assets/sovran-hub-icon.svg diff --git a/iso/assets/sovran-hub-icon.svg b/iso/assets/sovran-hub-icon.svg new file mode 100644 index 0000000..66d6123 --- /dev/null +++ b/iso/assets/sovran-hub-icon.svg @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- 2.54.0