initial commit

docs/getting-started/add-configs.md

@@ -0,0 +1,48 @@
+# Add NixOS and Home Manager configurations
+
+Choose a configuration template from [this list](https://git.sid.ovh/sid/synix/tree/master/apps/create/templates).
+
+Run the `create` script to add your desired configuration template to your nix-config flake:
+
+```bash
+nix --experimental-features "nix-command flakes" run git+https://git.sid.ovh/sid/synix#apps.x86_64-linux.create -- \
+-t TEMPLATE \
+-u USERNAME \
+-H HOST \
+--git-name GIT_NAME \
+--git-email GIT_EMAIL \
+-f ~/.config/nixos
+```
+
+> Change the architecture if needed. Supported architectures are listet under `supportedSystems` inside [`flake.nix`](https://git.sid.ovh/sid/synix/blob/master/flake.nix).
+
+See the script's help page for reference:
+
+```
+Usage: create -t|--template TEMPLATE -u|--user USERNAME -H|--host HOSTNAME [-f|--flake PATH/TO/YOUR/NIX-CONFIG] [--git-name GIT_NAME] [--git-email GIT_EMAIL]
+
+Options:
+    -t, --template TEMPLATE    Configuration template to use (mandatory)
+    -u, --user USERNAME        Specify the username (mandatory)
+    -H, --host HOSTNAME        Specify the hostname (mandatory)
+    -f, --flake FLAKE          Path to your flake directory (optional, default: ~/.config/nixos)
+    --git-name GIT_NAME        Specify the git name (optional, default: USERNAME)
+    --git-email GIT_EMAIL      Specify the git email (optional, default: USERNAME@HOSTNAME)
+    -h, --help                 Show this help message
+
+Available configuration templates:
+    hyprland
+    server
+    pi4
+    vm-uefi
+```
+
+All templates should work right out of the box. You only need to edit the disk partitioning script (`disks.sh`) or provide a [disko](https://github.com/nix-community/disko) configuration (`disko.nix`) in your host directory. A basic single disk partitioning script is provided. Set your disk by its ID, which comes from `ls -lAh /dev/disk/by-id`.
+
+> Warning: The create script applies patch files. It will print what it patched to stdout. It is strongly recommended to verify them manually.
+
+If you like, you can lock your flake before committing by running:
+
+```bash
+nix --experimental-features "nix-command flakes" flake lock
+```

docs/getting-started/create-nix-config.md

@@ -0,0 +1,30 @@
+# Create your own nix-config flake
+
+Create an empty directory and apply a [nix-config template](https://git.sid.ovh/sid/synix/tree/master/templates/nix-config) to it:
+
+```bash
+mkdir -p ~/.config/nixos
+cd ~/.config/nixos
+nix flake init -t "git+https://git.sid.ovh/sid/synix#templates.TEMPLATE"
+```
+
+Available templates are:
+- hetzner-amd
+- hyprland
+- pi4
+- server
+- vm-uefi
+
+> Note: You do not have to use `~/.config/nixos`, but configuration related scripts in this repository will use this directory as the default nix-config flake directory.
+
+Alternatively, use this flake's create script:
+
+```bash
+nix run "git+https://git.sid.ovh/sid/synix#create" -- -t TEMPLATE -u YOUR_USER -h YOUR_HOSTNAME
+```
+
+Check:
+
+```bash
+nix run "git+https://git.sid.ovh/sid/synix#create" -- --help
+```

docs/getting-started/install-instructions.md

@@ -0,0 +1,127 @@
+# Installation Guide
+
+This guide will walk you through installing NixOS using the provided installation script [`install.sh`](https://git.sid.ovh/sid/synix/blob/master/apps/install/install.sh).
+
+## Prerequisites
+
+1. **Bootable NixOS Installation Medium**: Make sure you have booted into NixOS live environment from the [Minimal ISO image](https://nixos.org/download/#nixos-iso). Read the [official NixOS installation guide](https://nixos.org/manual/nixos/unstable/#sec-obtaining) for more information on how to create a bootable NixOS USB drive.
+1. **Network Connection**: Ensure the target machine is connected to the internet.
+1. **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.
+1. **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.
+1. Go to `Video <some name>` and select `Virtio` under `Model`. Check `3D acceleration`.
+1. Click `Begin installation` in the top left corner.
+
+If you get the error:
+
+```plaintext
+Unable to complete install: 'unsupported configuration: domain configuration does not support video model 'virtio''
+```
+
+Install the package `qemu-full`:
+
+```shell
+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:
+
+```bash
+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:
+
+```bash
+sudo -i
+```
+
+### 2. Run the Install Script
+Download the install script to the target machine and run it:
+
+```bash
+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:
+
+```bash
+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`
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+nix-shell ~/.config/nixos/shell.nix --run 'rebuild home'
+```
+
+### 8. Reboot your System
+Once the home-manager configuration is applied, reboot your system:
+
+```bash
+sudo reboot now
+```
+
+You may now log in. Your system is now fully configured.