ftmahringer/nixos-config

This is my nixos-config, i have been building for some time now.

The biggest inspiration, was from: librephoenix and his nixos-config.

The main layout i took from him, as well as the idea with a custom wrapper script, which i have never seen someone else do before, i extended it and made that sciript a core part of my config.

---

Modular NixOS and Home Manager configuration for multiple hosts, built around:

• flake-parts
• Phoenix-style host folders
• shared modules/system, modules/user, and modules/themes
• a custom wrapper command: ftnix

Overview

This repo separates concerns like this:

• hosts/<name>/configuration.nix: host and system-facing settings
• hosts/<name>/home.nix: user and workflow-facing settings
• modules/system: shared NixOS modules
• modules/user: shared Home Manager modules
• modules/themes: theme definitions only
• config/variables.nix: bootstrap settings shared across all hosts
• config/ssh-hosts.nix: fixed extra SSH hosts that should always be present in ~/.ssh/config
• disko/: optional Disko layouts for fresh installs

Current hosts:

• nixos
• minipc

Host Layout

Each host follows this layout:

hosts/<name>/
├── default.nix
├── configuration.nix
├── home.nix
└── hardware-configuration.nix

• default.nix wires the host into NixOS + Home Manager
• configuration.nix defines host settings and system-specific config
• home.nix defines user-facing settings
• hardware-configuration.nix stays machine-specific

For new machines, hosts/TEMPLATE/ is the canonical starting point. That template is also used by ftnix docs generate as the source of truth for host-template schema docs.

Settings Style

The repo prefers nested feature blocks with .enable flags when a feature is optional.

Examples:

stylix = {
  theme = "dracula";
  icons = "papirus";
};

desktop = {
  compositor = "hyprland";
  type = "wayland";
  greeter = {
    name = "tuigreet";
  };
};

browser = {
  default = "librewolf";
  extra = [ "brave" ];
};

Single-choice tools usually stay simple:

launcher = "fuzzel";
bar = "waybar";
notifications = "mako";
fileManager = "yazi";

Some values are intentionally kept flat because they are always needed:

• system
• hostId
• hostname
• username
• fullName
• email
• homeDirectory
• timezone
• locale

The host template files also use a normalized metadata comment format so the wrapper can generate docs from them consistently:

• @section id=... title="..."
• @desc ...
• @field path=... type=... required=...
• @options option1|option2|...
• @shape ...
• @note ...

Themes

Themes live only in modules/themes/<name>/.

Each theme is expected to be self-contained and may include:

• a palette
• wallpaper/background info
• optional built-in asset selections for icons, fonts, and cursor family

If a theme has a local background file, that wins. Otherwise the theme can fall back to a URL + hash, and finally to the repo root wallpaper.png.

Useful theme commands:

ftnix stylix themes
ftnix stylix icons
ftnix stylix fonts
ftnix stylix cursors

The docs generator also builds a dedicated theming wiki page from the current repo structure, built-in asset catalog, and theme template files.

Wrapper

The main entrypoint is ftnix, installed from modules/system/ftnix/.

It is the preferred way to work with this repo instead of calling nixos-rebuild directly.

Common commands:

ftnix hosts
ftnix docs
ftnix docs commands
ftnix docs layout
ftnix docs host minipc
ftnix docs generate
ftnix docs wipe
ftnix docs pull
ftnix docs push
ftnix switch
ftnix switch --host minipc
ftnix remote-switch minipc
ftnix home switch
ftnix update
ftnix fmt
ftnix check
ftnix gc

Local switching

ftnix switch

This now auto-detects the current machine and uses the matching host by default.

You can still override it explicitly:

ftnix switch --host nixos

Remote switching

ftnix remote-switch minipc

This is intentionally separate from local switching.

• switch is local
• remote-switch <hostname|ip> is remote

remote-switch resolves the given SSH target back to a known host entry and refuses mismatches, so you cannot accidentally activate one host's config on a different machine.

Repo docs from the wrapper

ftnix docs
ftnix docs commands
ftnix docs layout
ftnix docs all
ftnix docs host nixos
ftnix docs generate
ftnix docs pull
ftnix docs push

This gives you a terminal-side explanation of:

• what the wrapper commands do
• how hosts/<name>/default.nix, configuration.nix, home.nix, and hardware-configuration.nix fit together
• a summary of the actual settings for a selected host
• how the theming system is wired
• how hosts/TEMPLATE is structured and documented

It can also manage the repository wiki through a local nested checkout in wiki/:

• ftnix docs generate writes generated Markdown wiki pages into wiki/
• ftnix docs wipe removes only the files previously generated by ftnix
• ftnix docs pull clones or pulls the remote repo wiki into wiki/
• ftnix docs push commits and pushes local wiki changes

Generated wiki pages currently include:

• Wrapper-Commands.md
• Host-Layout.md
• Host-Template.md
• Theming-System.md
• Hosts.md
• one page per configured host

The host-template page is generated from the normalized metadata comments in:

• hosts/TEMPLATE/configuration.nix
• hosts/TEMPLATE/home.nix

That means the template comments are intended to be maintained as the source of truth for supported host and user settings shapes.

Host Template

hosts/TEMPLATE/ is the recommended way to add a new host.

It contains:

• default.nix: wiring for NixOS + Home Manager
• configuration.nix: host and system-facing settings
• home.nix: user and workflow-facing settings
• hardware-configuration.nix: hardware placeholder to replace on the real machine

The template intentionally includes more settings than a minimal host needs. The normal workflow is:

1. copy hosts/TEMPLATE/ to hosts/<name>/
2. replace placeholders like HOSTNAME, USERNAME, NAME, and EMAIL
3. remove sections you do not need
4. keep the remaining settings shape consistent with the shared modules

The normalized metadata exists to keep this maintainable:

• options are always declared through @options ...
• field shapes like single-choice, list, or default+extra attrset are explicit
• descriptions, notes, and examples are structured enough for ftnix docs generate

Container Registries

For Docker or Podman hosts, you can define shared container registry settings directly in the host's virtualisation block:

virtualisation = {
  containerRuntime = "podman";
  registries = {
    search = [ "nexus.example.com" ];
    insecure = [ "nexus.example.com" ];
    block = [ ];
  };
};

This maps to the shared NixOS container registry settings, so the same host config shape works for both Podman and Docker.

SSH Config Generation

Home Manager owns ~/.ssh/config.

The SSH config is built from two sources:

1. generated host entries from the repo's host definitions
2. fixed extra hosts from config/ssh-hosts.nix

On ftnix switch, the wrapper updates the current host's ssh.hostName to the current detected IPv4 and writes a generated repo-side SSH file. Then Home Manager regenerates the real ~/.ssh/config during activation.

That means:

• ftnix does not write directly to ~/.ssh/config
• custom manual entries should go into ~/.ssh/config.local
• fixed repo-managed custom entries should go into config/ssh-hosts.nix

Example config/ssh-hosts.nix:

{
  forgejo = {
    hostname = "forgejo.ftmahringer.com";
    user = "git";
    port = 2222;
    identityFile = [ "~/.ssh/id_ed25519" ];
    identitiesOnly = true;
  };
}

Current Shared Features

Notable shared pieces already wired into the repo:

• Stylix theming
• Hyprland desktop setup
• greetd + tuigreet
• firewall module
• SSH service
• ZRAM/sysctl tuning support
• Disko support
• generated SSH config via Home Manager
• nix-output-monitor integration in ftnix

Disko

Disko is available, but optional.

Hosts can either use a real layout:

disko = {
  enable = true;
  layout = "single-disk-ext4";
  device = "/dev/sda";
};

or an intentionally empty disabled shape:

disko = { };

Development Notes

Formatting and checks:

ftnix fmt
ftnix check

The repo also includes pre-commit hook wiring in the flake, so once the lockfile/input state is up to date you can use normal pre-commit formatting as well.

If the git hook ever points at a stale Nix store path again, refresh it with:

nix develop

Preferred Workflow

For normal use:

ftnix switch

For another local host config:

ftnix switch --host minipc

For a remote activation:

ftnix remote-switch minipc

If the wrapper is ever the thing being fixed and you need a bootstrap rebuild, use direct nixos-rebuild once:

sudo nixos-rebuild switch --flake .#minipc

After that, go back to ftnix.