Post-Installation Guide¶

Welcome to your new tuinix system! This guide covers what to expect after your first boot and how to customise and maintain your system.

First boot¶

After installation and reboot:

GRUB loads automatically
You'll be prompted for your ZFS encryption passphrase (if using ZFS encryption)
The system boots to a terminal login prompt
Log in with the username and password you set during installation

Your environment¶

tuinix is a terminal-only system. There is no desktop environment, no window manager, and no graphical login screen. Everything is done from the command line.

Your system includes:

Shell: A modern shell with intelligent completions
Multiplexer: Terminal multiplexer for managing multiple sessions
Editor: Terminal-based text editors
File manager: Terminal file browser
System monitoring: Resource monitoring tools
Networking: WiFi and ethernet management tools
Development: Git and common development utilities

Your flake¶

Your entire system configuration lives in a single git repository in your home directory:

~/tuinix/                      <-- your git repo (you own this)
  flake.nix                    <-- main flake definition
  flake.lock                   <-- pinned dependency versions
  hosts/<hostname>/            <-- your machine's configuration
    default.nix                <-- system config (packages, services, etc.)
    hardware.nix               <-- hardware-specific settings
    disks.nix                  <-- disk layout (generated by installer)
  users/<username>.nix         <-- your user config (packages, git, etc.)
  modules/                     <-- tuinix module library
  templates/                   <-- disk layout templates

/etc/tuinix -> ~/tuinix        <-- symlink (so root can find the flake)

The installer cloned the upstream tuinix repo, added your generated host and user configuration, committed everything, and set ownership to your user account. Git is pre-configured with your name and email so you can start making changes immediately.

Modifying your system¶

The workflow for changing your system is:

Edit configuration files in ~/tuinix
Rebuild to apply the changes
Commit to record what you changed

Quick example: add a package¶

cd ~/tuinix

# Edit your host config
vim hosts/$(hostname)/default.nix

Find the environment.systemPackages section and add packages:

environment.systemPackages = with pkgs; [
  vim
  git
  curl
  wget
  htop
  tree
  # Add your packages here:
  ripgrep
  fzf
  eza
];

Rebuild and commit:

sudo nixos-rebuild switch --flake .#$(hostname)
git add -A && git commit -m "Add ripgrep, fzf, eza"

Using rebuild.sh¶

The scripts/rebuild.sh helper handles the full rebuild cycle for you:

cd ~/tuinix
./scripts/rebuild.sh              # default: nixos-rebuild switch
./scripts/rebuild.sh test         # test without making it the boot default
./scripts/rebuild.sh boot         # apply at next reboot only

What you can change¶

File	What it controls
`hosts/<hostname>/default.nix`	System packages, services, networking, locale
`users/<username>.nix`	Your user account, groups, git config, home-manager
`modules/`	Shared tuinix modules (SSH, firewall, ZFS, display, etc.)
`flake.nix`	Flake inputs, dev shell, build outputs
`flake.lock`	Pinned versions of nixpkgs and other inputs

Enabling or disabling modules¶

tuinix modules are toggled with tuinix.* options in your host config:

# In hosts/<hostname>/default.nix
{
  # Networking
  tuinix.networking.networkmanager.enable = true;
  tuinix.networking.iphone-tethering.enable = true;

  # Security
  tuinix.security.ssh.enable = true;
  tuinix.security.ssh.port = 22;
  tuinix.security.firewall.enable = true;

  # Storage
  tuinix.zfs.enable = true;
  tuinix.zfs.encryption = true;

  # Display
  tuinix.display.resolution = "1920x1080";  # or null for auto-detect
}

Pulling upstream updates¶

The tuinix project receives improvements over time. To merge them into your system:

cd ~/tuinix
git remote -v                    # verify 'origin' points to upstream
git pull --rebase                # rebase your commits on top of upstream
sudo nixos-rebuild switch --flake .#$(hostname)
git add -A && git commit -m "Merge upstream tuinix updates"

If you get merge conflicts, resolve them in the affected files, then:

git add <resolved-files>
git rebase --continue

Updating nixpkgs¶

To get newer package versions (security patches, new software releases):

cd ~/tuinix
nix flake update                 # updates flake.lock to latest nixpkgs
sudo nixos-rebuild switch --flake .#$(hostname)
git add flake.lock && git commit -m "Update flake inputs"

Rolling back¶

NixOS keeps previous system generations. If a rebuild breaks something:

# List available generations
sudo nix-env --list-generations -p /nix/var/nix/profiles/system

# Roll back to the previous generation
sudo nixos-rebuild switch --flake .#$(hostname) --rollback

Or select a previous generation from the GRUB boot menu at startup.

Networking¶

Ethernet¶

Wired connections work automatically via DHCP.

WiFi¶

# Interactive TUI
nmtui

# Or use the CLI
nmcli device wifi list
nmcli device wifi connect "SSID" password "password"

iPhone USB tethering¶

If enabled during installation, plug in your iPhone via USB and it will be detected automatically as a network interface.

Backup your configuration¶

Your ~/tuinix repo is your entire system definition. Back it up by pushing to a remote:

cd ~/tuinix
# Add your own remote (e.g. a private GitHub repo)
git remote add mine git@github.com:yourusername/my-tuinix.git
git push -u mine main

This gives you a complete backup of your system configuration that you can use to reproduce your exact setup on another machine.

Next steps¶

Browse available packages at search.nixos.org
Learn about ZFS management (snapshots, scrubs, health checks)
Explore the tuinix modules in the modules/ directory
Read the NixOS manual for advanced configuration

Made with by Kartoza | Donate | GitHub