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) · Public site

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.

What This Repo Is
Architecture
Module Catalog
The Three Modes (internal reference)
Build & Deploy Reference
Networking & Reverse Proxy
Security Posture
Backups & Recovery
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.
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.

_{Internal mirror. Public copy lives on Gitea.}

8.9 KiB Raw Blame History