Technical Documentation
Click to expand
1. Introduction
Declarative Technologies delivers a NixOS 25.05 workstation image with an “it-works-my-way” philosophy; one repo, one stack, minimal tuning knobs. The current build targets single-user desktops and small office servers rather than large fleets; anything outside that scope is aspirational, so it isn’t listed here.
2. System Architecture
| Layer | What You Really Use | Notes |
|---|---|---|
| Boot | systemd-boot on EFI/BOOT | Simple; no GRUB complexity. |
| Root FS | (If using NVMe) Btrfs on a single partition, mounted via subvolume @(If other) EXT4, with volume for root and home. Dedicated 8GB swap partition for RAM cache offloading. | BTRFS chosen for snapshots & compression; no ZFS (compression) present. EXT4 chosen for reliability and ubiquity |
| Config Source | Git monorepo at /etc/nixos | flakes, home-manager, flake-parts, plasma-manager, etc. |
| Update Flow | switch.sh script → git pull (from private repo with deploy key) → nix flake update → nixos-rebuild switch | Runs on every manual call; throttles flake update to 10 min. No CI, no signing. |
| Networking | NetworkManager + Tailscale + Headscale on management network. Prometheus + Grafana (system monitoring) | Tailscale set to client routing; no exit nodes. Performance metrics scraped by Prometheus. Grafana for admin to review client uptime, with multiple redundant alert systems. |
| Display Stack | KDE Plasma (X11) + Proprietary drivers for hardware | hardware.graphics.enable, PRIME offload for laptops |
Filesystem & Snapshotting
- Btrfs snapshots are manual only – there is no automatic timeline, rollback helper, or remote replication (yet)
- Swap lives on a dedicated
swaplabel partition; nothing fancy.
Monorepo Layout
/etc/nixos
├──flake.nix
├──flake.lock
├── hosts/
├── sys-modules/
├──home-modules/
├── scripts/
└── hardware-configuration.nix
Everything (including flake.lock) is committed so rebuilds are deterministic; you don’t regenerate the lock on the fly.
3. Software Stack
| Category | Enabled Modules / Packages | Comment |
|---|---|---|
| Desktop | plasma DE. papirus Icon theme | |
| Browsers | Firefox, Chrome | |
| Office / Mail | LibreOffice, OnlyOffice, Evolution, Thunderbird, Birdtray | |
| Dev Tooling | nixvim, nixpkgs-fmt, morph | NixVim is byte-compiled Lua; Gruvbox theme; LazyGit keybind. (dev tools) |
| Media | VLC | |
| Virtualisation | VirtualBox + extension pack | For Windows VMs if you must. |
| Comms | Microsoft Teams, Signal Desktop | Signal is a privacy focused messaging app |
| Networking & VPN | Tailscale / Headscale Prometheus / Grafana | Provides convenient remote access for DecTech staff to handle updates and confirm uptime. * |
| Misc Utilities | Htop, GParted, Baobab, Remotemouse, SSHFS, windows-reboot | Last one allows password-less reboot into the Windows bootloader entry. |
* DecTech requires permanent connections via secure networking tunnel to ensure uptime via Prometheus system monitoring. DecTech requires explicit permission for remote support – We will not invade your employee’s privacy, or monitor for inappropriate usage of your company machines. Our network tunnel only permits connections to our server via SSH and Prometheus (no graphical interface)
4. Security Posture
Firewall: On – All ports blocked. Only the Tailscale interface is trusted for remote management via SSH and Prometheus
Bluetooth: Enabled and discoverable.
Sudo: Client computers do not have have sudo privileges.
Unfree Drivers: nixpkgs.config.allowUnfree = true to pull NVIDIA display drivers if necessary.
Remote Support: We are able to diagnose and repair issues remotely via SSH (we don’t need to disrupt your work to fix something)
5. Update & Maintenance Workflow
[placeholder]
graph TD
A [Run switch.sh] –> B [ssh-agent loads read-only key]
B –> C [git fetch && reset –hard origin/main]
C –> D [Optional nix flake update]
D –> E [nixos-rebuild switch]
E –> F [Reboot if needed]
Trigger: Manual; no cron or timer (this is a good thing – we vet and monitor every computer on your network, one by one, to ensure system uptime stays above 99.9%)
Downtime: One after-hours reboot max (for kernel updates); otherwise, your computers will update in the background without you even noticing, with absolutely no disruptions to your machines.
Rollback: Standard NixOS boot-loader entry; no wrapper script yet.
Limitations & Roadmap
Click to expand
Limitations
- No CI / Cachix – All builds happen on each host; slow and brittle (though not an issue due to updates outside of business hours)
- Secret Management – No
sops-nixyet; secrets baked into configuration modules or local files. - Cloud Storage – Client’s server / Dropbox is preferred method for data integrity.
Roadmap
| Priority | Task | Requires |
|---|---|---|
| P1 | Thorough audit to ensure all modules and scripts run independent of username | Time |
| P2 | Multi-user management systems via Nextcloud/Syncthing | Implementation |
| P3 | Secure cloud management for local files. | Additional infrastructure for RAID-style backup |
| P4 | a. Integrate sops-nix for secretsb. Make rollbacks automatic if system fails to boot | a. YubiKey or HSM rollout. b. bootscript |
| PX |
History
2025-08-04
Implementation of Tailscale / Headscale / Prometheus / Grafana complete. Created automated scripts to handle setup of authentication keys on remote-server.