synix/docs/getting-started/install-instructions.md

Installation Guide

This guide will walk you through installing NixOS using the provided installation script install.sh.

Prerequisites

1. Bootable NixOS Installation Medium: Make sure you have booted into NixOS live environment from the Minimal ISO image. Read the official NixOS installation guide for more information on how to create a bootable NixOS USB drive.
2. Network Connection: Ensure the target machine is connected to the internet.
3. Host configuration: The target machine needs to have a working NixOS configuration inside your own flake. A hardware configuration is not required as it can be generated automatically during installation.
4. Disks setup: The target machine needs to have a working disk configuration or partitioning script inside hosts/HOSTNAME. Disko expects its configuration to be in hosts/HOSTNAME/disks.nix. Alternatively, a shell script can be provided at hosts/HOSTNAME/disks.sh that will format, partition, and mount disks.

Using UEFI is recommended.

Optional: Virt-Manager config for Wayland

If you want to install NixOS with Wayland support inside a VM using Virt-Manager, enable 3D acceleration by checking Customize configuration before install:

1. Go to Display <VNC or Spice> and select Spice Server under Type. Select None under Listen type. Check OpenGL and select a device that is not from Nvidia.
2. Go to Video <some name> and select Virtio under Model. Check 3D acceleration.
3. Click Begin installation in the top left corner.

If you get the error:

Unable to complete install: 'unsupported configuration: domain configuration does not support video model 'virtio''

Install the package qemu-full:

sudo pacman -Syy qemu-full

assuming you are on Arch Linux

Then, reboot.

Steps

Boot into NixOS ISO image on your target machine.

0. SSH into the Target Machine

If you are using a remote machine, set a password for the user nixos using passwd. Then, SSH into it using the following command:

ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no nixos@<host-ip-address>

Replace <host-ip-address> with the IP address of the target machine which can be found using ip a.

1. Become root

The default user nixos has sudo privileges. Become root to run the install script:

sudo -i

2. Run the Install Script

Download the install script to the target machine and run it:

nix --experimental-features "nix-command flakes" run git+https://git.sid.ovh/sid/synix#apps.x86_64-linux.install -- \
-n HOST \
-r REPOSITORY

Replace HOST with the name of your target machine.
Replace REPOSITORY with your flake URL.
You can specify a branch with -b BRANCH (default: master)
Print the usage page with -h.
Change the architecture if needed.

Tip: If your Flake is not a public Git repository, you may provide the source code manually. First, copy your Flake directory to /tmp/nixos on the host machine. Then, you can omit the -r flag.

3. Reboot your System

Once the installation completes, unmount the installation medium:

umount -Rl /mnt

If you have your root file system on ZFS, export all pools: zpool export -a

Then, you can safely remove the installation medium and reboot your machine:

If you generated a new hardware configuration, you should save it before rebooting:
cat /tmp/nixos/hosts/HOSTNAME/hardware.nix

reboot now

4. Login

Upon reboot, your system will boot into the newly installed NixOS. Login as a valid user defined in the configuration of the host (hosts/HOSTNAME/default.nix). The default initial password is changeme. Change your password with passwd after login.

5. Optional: Import age keys

If you use sops-nix with age in you Home Manager configuration, you need to import your age keys:

mkdir -p ~/.config/sops/age
cp /PATH/TO/YOUR/keys.txt ~/.config/sops/age/keys.txt

6. Clone your Repository

Git is installed on every system by default. Clone your flake repository to your home directory:

git clone YOUR_GIT_REPO_URL ~/.config/nixos

The rebuild script expects your flake to be in ~/.config/nixos

7. Apply your Home Manager Configuration

Home Manager is not installed by default. Enter the development shell to apply the configuration:

nix-shell ~/.config/nixos/shell.nix --run 'rebuild home'

8. Reboot your System

Once the home-manager configuration is applied, reboot your system:

sudo reboot now

You may now log in. Your system is now fully configured.