sid/synix
1
0
Fork 0
Code Issues 7 Pull requests 1 Projects Activity Actions

initial commit
All checks were successful
Deploy docs / build-and-deploy (push) Successful in 3s
Details

Browse source
This commit is contained in:
sid 2026-02-23 20:34:35 +01:00
commit 95a533c876
451 changed files with 18255 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

48
docs/getting-started/add-configs.md Normal file
View file

@ -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
```

30
docs/getting-started/create-nix-config.md Normal file
View file

@ -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
```

127
docs/getting-started/install-instructions.md Normal file
View file

@ -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.

12
docs/index.md Normal file
View file

@ -0,0 +1,12 @@
# synix docs
Welcome to the documentation for [synix](https://git.sid.ovh/sid/synix).
The goal of this project is to provide modules and packages for your NixOS and Home Manager configurations, suitable for client and server applications. Scripts are also included to automate the creation and installation of your own flake.
## Explore the documentation:
- **Introduction to Nix**: Understand the fundamentals of the Nix language and package manager, as well as NixOS. Start here if you are new.
- **Getting Started:** A guide to go from scratch to a complete, working NixOS configuration using synix. Start here if you know about Nix and NixOS.
- **Modules:** Information about available NixOS and Home Manager modules.
- **Tips:** Find recommendations and resources to navigate the Nix ecosystem.

92
docs/introduction-to-nix/derivations.md Normal file
View file

@ -0,0 +1,92 @@
# Derivations
At its core, Nix is about building software. Nix doesn't install software directly from a global repository; instead, it builds *derivations*. A derivation is a description of how to build a package. It's a pure function `inputs -> output`, meaning given the same inputs, it will always produce the same output.
## Your first Derivation
Let's build a simple "hello world" program.
First, create a C source file `hello.c`:
```c
// hello.c
#include <stdio.h>
int main() {
printf("Hello from C!\n");
return 0;
}
```
Then, create a `default.nix` file that imports Nixpkgs and then calls the package definition below.
```nix
# default.nix
{ pkgs ? import <nixpkgs> {} }: # Fetch Nixpkgs
# Nixpkgs is a collection of Nix expressions.
# We need some functions (like `callPackage`) that are defined there.
# Nixpkgs will be covered later in this guide.
pkgs.callPackage ./my-hello.nix { }
# `callPackage` is a helper function for Package derivations.
# It automatically resolves all needed input arguments the derivation needs from Nixpkgs.
```
> Hint: `default.nix` will get replaced by Nix Flakes later. You do not need to know what Flakes are at the moment, but keep this relationship in mind.
Now, define how to build the C source file a Nix file, `my-hello`.nix:
```nix
# my-hello.nix
{ stdenv }: # Inputs
stdenv.mkDerivation {
pname = "my-hello"; # Package name
version = "0.1.0"; # Package version
src = ./.; # The source code for the package is in the current directory
# Phases of the build process
# mkDerivation defines standard phases like unpackPhase, patchPhase, configurePhase, buildPhase, installPhase
# For simple builds, we just need build and install.
buildPhase = ''
# Compile command
${stdenv.cc}/bin/gcc hello.c -o hello
'';
installPhase = ''
# Install the compiled program into the output directory ($out)
mkdir -p $out/bin
cp hello $out/bin/hello
'';
}
```
Let's break this down:
- `stdenv`: This derivation is a function that expects `stdenv` (standard environment, providing common build tools and phases) as an argument. It will be automatically resolved from Nixpkgs.
- `stdenv.mkDerivation`: This is the core function to create a derivation. It sets up a standard build environment and provides a set of common build phases.
- `pname`, `version`: Standard metadata for the package.
- `src = ./.;`: This tells Nix to copy all files from the current directory into the build sandbox.
- `buildPhase`: This is where you put commands to compile your software. Here, `gcc` is used from the standard C compiler provided by `stdenv.cc` to compile `hello.c` into an executable `hello`.
- `installPhase`: This is where you put commands to install the build artifacts into the `$out` directory, which is the final location in the Nix store. Here, a `bin` directory is created to move the `hello` executable into.
## Building and Running a Derivation
To build this derivation, use `nix build`:
```bash
nix build --file default.nix
```
You'll see output from the build process. If successful, Nix creates a `result` symlink in your current directory. This `result` symlink points to the package in the Nix store.
Now, run your compiled program:
```bash
./result/bin/hello
```
```
Hello from C!
```

209
docs/introduction-to-nix/flakes.md Normal file
View file

@ -0,0 +1,209 @@
# Flakes
> Flakes are still an experimental feature in Nix. However, they are so widely used by the community that they almost became standard. Furthermore, *synix* uses Flakes.
Nix flakes are a reproducible way to define, build, and deploy Nix projects, making them reliable and portable.
Flakes accomplish that by:
## Standardized Input
They define a fixed, declarative input (the `flake.nix` file) that specifies all project dependencies, sources, and outputs. This eliminates implicit dependencies or environment variables that could cause builds to differ.
Example in `flake.nix`:
```nix
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11"; # Declare we need nixpkgs, specifically this branch
};
```
## Reproducible "Lock File"
When you build or develop with a flake, Nix generates a `flake.lock` file. This file records the *exact* content-addressable hashes of *all* transitive inputs used for that specific build. This lock file can be committed to version control, ensuring that anyone else cloning the repository (or a CI system) will use precisely the same set of inputs and thus achieve the identical result.
Example `flake.lock` entry for `nixpkgs`:
```json
"nixpkgs": {
"locked": {
"lastModified": 1709259160,
"narHash": "sha256-...",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "b2f67f0b5d1a8e1b3c9f2d1e0f0e0c0b0a090807", // The exact commit!
"type": "github"
},
"original": {
"owner": "NixOS",
"repo": "nixpkgs",
"type": "github",
"url": "github:NixOS/nixpkgs/nixos-23.11"
}
}
```
## Flake Schema
The `flake.nix` has a well-defined structure for `inputs` (sources like Git repos, other flakes) and `outputs` (packages, applications, modules, etc.). This consistent schema makes flakes composable and predictable.
A `flake.nix` file typically looks like this:
```nix
# flake.nix
{
description = "A simple example flake";
inputs = {
# Inputs are other flakes or external resources
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11"; # Locked to a specific branch/version
# This is how you would add synix to your flake:
# synix.url = "git+https://git.sid.ovh/sid/synix"
};
outputs = { self, nixpkgs, ... }@inputs: # 'self' refers to this flake, inputs are available
let
# Define common arguments for packages from nixpkgs
# This ensures all packages use the same version of Nixpkgs on this system
pkgs = import nixpkgs {
system = "x86_64-linux"; # The target system architecture
};
in
{
# Outputs include packages, devShells, modules, etc.
# Packages that can be built by `nix build .#<package-name>`
packages.x86_64-linux.my-app = pkgs.callPackage ./pkgs/my-app { };
packages.x86_64-linux.my-other-app = pkgs.hello; # From nixpkgs directly
# Development shells that can be entered using `nix develop`
devShells.x86_64-linux.default = pkgs.mkShell {
name = "my-dev-env";
buildInputs = [ pkgs.nodejs pkgs.python3 ];
shellHook = "echo 'Welcome to my dev environment!'";
};
# NixOS modules (for system config)
# nixosConfigurations.<hostname>.modules = [ ./nixos-modules/webserver.nix ];
# (This is more advanced and will be covered in NixOS section)
};
}
```
Key parts of a `flake.nix`:
- `description`: A human-readable description of your flake.
- `inputs`: Defines all dependencies of your flake. Each input has a `url` pointing to another flake (e.g., a GitHub repository, a local path, or a Git URL) and an optional `follows` attribute to link inputs.
- `outputs`: A function that takes `self` (this flake) and all `inputs` as arguments. It returns an attribute set defining what this flake provides. Common outputs are `packages`, `devShells`, `nixosConfigurations`, etc., usually segregated by system architecture. You can read more about flake outputs in the [NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/other-usage-of-flakes/outputs).
## `nix flake` Commands
The `nix flake` subcommand is your primary interface for interacting with flakes. Let's create a new flake to demonstrate them:
Initialize the flake:
```bash
mkdir my-flake && cd my-flake
nix flake init
```
This creates a minimal `flake.nix`.
Lock your flake:
```bash
nix flake lock
```
This creates `flake.lock`, a file that locks the exact versions of your inputs.
Update flake inputs:
```bash
nix flake update
```
This updates all inputs to their latest versions allowed by their `url` (e.g., the latest commit on `nixos-unstable` for `nixpkgs`) and then updates the `flake.lock` file. Since we just locked the flake for the first time, there probably won't be any updates available.
Print flake inputs:
```bash
nix flake metadata
```
Print flake outputs:
```bash
nix flake show
```
Build packages from a flake:
```bash
nix build .#hello # The '.' refers to the current directory's flake
./result/bin/hello
```
Run a package from a flake:
```bash
nix run .#hello
```
Since the `packages.<system>.default` output exists, you can just do `nix run`.
## `nix develop`
This command spins up a temporary shell environment with all the tools and dependencies specified in your flake's `devShells` output.
Let's expand your `flake.nix`:
```nix
# flake.nix
{
description = "A very basic flake";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
};
outputs =
{ self, nixpkgs }:
let
# Define `pkgs` for the current system
pkgs = import nixpkgs {
system = "x86_64-linux";
};
in
{
packages.x86_64-linux.hello = nixpkgs.legacyPackages.x86_64-linux.hello;
# With `pkgs` defined, we could also do this:
# packages.x86_64-linux.hello = pkgs.hello;
packages.x86_64-linux.default = self.packages.x86_64-linux.hello;
devShells.x86_64-linux.default = pkgs.mkShell {
# Packages available in the shell
packages = [
pkgs.git
pkgs.go
pkgs.neovim
];
# Environment variables for the shell
GIT_COMMITTER_EMAIL = "your-email@example.com";
# Commands to run when entering the shell
shellHook = ''
echo "Entering development shell for my project."
echo "You have Git, Go, and Neovim available."
'';
};
};
}
```
Now, from your project directory:
```bash
nix develop
```
You'll instantly find yourself in a shell where `git`, `go`, and `nvim` are available, and your `GIT_COMMITTER_EMAIL` is set. When you exit, your regular shell environment is restored – no lingering installations or modified global state. This makes it incredibly easy to switch between projects, each with its specific toolchain and dependencies, without conflicts.

22
docs/introduction-to-nix/install-nix.md Normal file
View file

@ -0,0 +1,22 @@
# Install Nix
Install the Nix package manager according to the official documentation on [nixos.org](https://nixos.org/download/).
On Linux, simply run:
```bash
sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon
```
## Configuration
Add the following to `~/.config/nix/nix.conf` (recommended) or `/etc/nix/nix.conf`:
```ini
experimental-features = nix-command flakes
```
- `nix-command` enables the [new `nix` CLI](https://nix.dev/manual/nix/2.29/command-ref/new-cli/nix.html) Nix is transitioning to.
- `flakes` will be covered later in this guide. Don't worry about them for now.
Reload your session to get access to the `nix` command.

227
docs/introduction-to-nix/nix-speedrun.md Normal file
View file

@ -0,0 +1,227 @@
# Nix Speedrun
This section will cover some Nix language basics as fast as possible.
## Comments
```nix
# This is a comment
/*
This is a block comment
*/
```
## Data types
Every value in Nix has a type. Some basic types are:
```nix
16 # integer
3.14 # float
false # boolean
"Hello, world!" # string
''
This is also a string,
but over multiple lines!
''
```
Assign a value to a variable:
```nix
myVar = "99";
```
And then inject it into a string:
```nix
''
I got ${myVar} problems,
but Nix ain't one.
''
```
Nix also has compound values. This is a list:
```nix
[ 123 "hello" true null [ 1 2 ] ]
```
You can mix different types in a list. This is an attribute set:
```nix
{
foo = 4.56;
bar = {
baz = "this";
qux = false;
};
}
```
An attribute set is like an object. It is a collection of name-value-pairs called *attributes*. The expression above is equivalent to:
```nix
{
foo = 4.56;
bar.baz = "this";
bar.qux = false;
}
```
## Evaluation
In Nix, everything is an expression that evaluates to a value. Create a `hello.nix`-file with the following content:
```nix
"Hello, world!"
```
Then, evaluate the file:
```bash
nix eval --file hello.nix
```
```
Hello, world!
```
A let-expression allows you to define local variables for an expression:
```nix
let
alice = {
name = "Alice";
age = "26";
};
in
''
Her name is ${alice.name}.
She is ${alice.age} years old.
''
```
## Functions
Functions have the following form:
```nix
pattern: body
```
The pattern specifies what the argument of the function must look like, and binds variables in the body to (parts of) the argument.
```nix
let
increment = num: num + 1;
in
increment 49
```
Functions can only have a single argument. For multiple arguments, nest functions:
```nix
let
isAllowedToDrive =
name: age:
if age >= 18 then "${name} is eligible to drive." else "${name} is too young to drive yet.";
in
isAllowedToDrive "Charlie" 19
```
It is common to pass multiple arguments in an attribute set instead. Since Nix is lazily evaluated, you can define multiple bindings in the same let-statement.
```nix
let
add = { a, b }: a + b;
result = add { a = 34; b = 35; };
in
result
```
You can also set optional arguments by providing default values:
```nix
let
greet = { greeting ? "Hello", name }: "${greeting}, ${name}!";
in
greet { name = "Bob"; }
```
Let's look at one last example:
```nix
let
myFunc = { a, b, c }: a + b * c;
numbers = {
a = 1;
b = 2;
c = 3;
};
result = myFunc { a = numbers.a; b = numbers.b; c = numbers.c; };
in
result
```
Nix provides some syntactical sugar to simplify that function call. The `with` keyword brings all attributes from an attribute set into the scope:
```nix
# ...
result = with numbers; myFunc { a = a; b = b; c = c; };
# ...
```
However, this syntax is discouraged. Use `inherit` instead to explicitly list attributes to bring into the scope:
```nix
# ...
inherit (numbers) a b c;
result = myFunc { inherit a b c; };
# ...
```
## Builtin functions
Nix provides [builtin functions](https://nix.dev/manual/nix/2.25/language/builtins) by default through the global `builtins` constant. For example, `builtins.attrNames` gives you a list of all attributes of the given attribute set:
```nix
builtins.attrNames { a = 1; b = 2; }
# => [ "a" "b" ]
```
> Yes, this means that attribute keys, though defined as variables, are available as strings.
Some builtins are so common that the `builtins` prefix can be omitted. `map` is a builtin function that applies a function to each element of a list.
```nix
# squares.nix
let
numbers = [ 5 2 1 4 3 ];
squares = map (n: n * n) numbers;
in
{
inherit numbers squares;
}
```
The `import` function allows to separate the codebase into multiple files:
```nix
# sort.nix
let
results = import ./squares.nix; # paths have their own type
inherit (results) squares;
inherit (builtins) sort lessThan;
in
sort lessThan squares
```
> The `sort` function can be found in the [Nix manual](https://nix.dev/manual/nix/2.25/language/builtins#builtins-sort).

40
docs/introduction-to-nix/nix-store.md Normal file
View file

@ -0,0 +1,40 @@
# Nix Store
You've built a package, and it landed in the `/nix/store`. The Nix store is the heart of Nix's reproducibility, atomicity, and rollback capabilities.
## Unique Paths (Hashing)
Every piece of software, configuration, or data managed by Nix lives in the Nix store under a unique, cryptographically hashed path. For example, `nix build` might produce something like:
```
/nix/store/zx9qxw749wmla1fad93al7yw2mg1jvzf-my-hello-0.1.0
```
A Nix store path consists of its hash and a human readable name with a version, which are defined in the corresponding derivation. The hash ensures:
1. **Immutability:** Entries in the Nix Store are read only. Once something is in the Nix store, it never changes. If you modify a source file or a build instruction, it creates a *new* derivation with a *new* hash, and thus a *new* path in the store. The old version remains untouched.
2. **Reproducibility:** If two different systems build the exact same derivation, they will produce the exact same hash and thus the exact same path. This guarantees that "it works on my machine" translates to "it works on *any* Nix machine."
3. **Collision Avoidance:** Because the path includes a hash of all its inputs (source code, build script, compiler, libraries, etc.), different versions or configurations of the same package can coexist peacefully in the store without conflicting.
You can inspect the contents of a store path directly:
```bash
ls -l /nix/store/zx9qxw749wmla1fad93al7yw2mg1jvzf-my-hello-0.1.0/bin
```
Replace the hash with the actual hash from your previous `nix build` command or `ls -l result`.
## Dependency Resolution
The Nix store is also a giant, explicit dependency graph.
When you define a derivation for `my-hello` that uses `stdenv` and `gcc`, Nix doesn't just build `my-hello`. It first ensures that `stdenv` and `gcc` (and their own dependencies, recursively) are also present in the Nix store.
Let's look at the dependencies of your `my-hello` derivation:
```bash
nix path-info --recursive ./result
```
This command will list all the Nix store paths that `my-hello` directly or indirectly depends on. You'll see things like `glibc`, `gcc`, and many other low-level system libraries. Each of these is itself a derivation built and stored in the Nix store under its own unique hash.
This means that conflicts are impossible because different versions of the same library (e.g., `libssl-1.0` and `libssl-3.0`) can coexist peacefully in `/nix/store` under their distinct hashes.

200
docs/introduction-to-nix/nixos.md Normal file
View file

@ -0,0 +1,200 @@
# NixOS
NixOS is a Linux distribution built entirely on top of the Nix package manager and the Nix language. This means your entire operating system, from the kernel to user-space applications and system services, is declared in a set of Nix expressions. This brings all the benefits of Nix (reproducibility, atomic upgrades, easy rollbacks) to your whole system.
## NixOS Configuration (with Flakes)
With flakes, your NixOS configuration typically resides in a `flake.nix` file that exports a `nixosConfigurations` output.
Let's have a look at a basic `flake.nix` for a NixOS machine.
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
};
outputs =
{
self, # The flake itself
nixpkgs, # The nixpkgs input
...
}@inputs: # `self` and `nixpkgs` are available under `inputs`
let
inherit (self) outputs;
in
{
# Define NixOS configurations
nixosConfigurations = {
# Name for this specific system configuration
your-pc = nixpkgs.lib.nixosSystem {
# Arguments passed to all NixOS modules
specialArgs = {
inherit inputs outputs;
};
# List of all configuration files (modules)
modules = [ ./configuration.nix ];
};
};
};
}
```
The `nixosSystem` function takes a list of `modules`. Each module is a Nix expression that defines desired system state and settings. So the actual system configuration lives in `configuration.nix`:
```nix
# configuration.nix
{ config, pkgs, ... }: # The arguments provided to a NixOS module
{
# Enable a display manager and desktop environment
services.displayManager.lightdm.enable = true;
services.desktopManager.gnome.enable = true; # Or kde, xfce, etc.
# List of packages to be installed globally
environment.systemPackages = with pkgs; [
firefox
neovim
git
];
# Configure networking
networking.hostName = "my-nixos-desktop";
# Users
users.users.Alice = {
isNormalUser = true;
extraGroups = [ "wheel" "networkmanager" ]; # Add user to groups for sudo and network management
initialPassword = "changeme"; # Set a temporary password
};
# Set system-wide locale
i18n.defaultLocale = "en_US.UTF-8";
# Set the system time zone
time.timeZone = "America/New_York";
# ... many more options ...
}
```
> Please note that the above configuration is not a complete working NixOS configuration. It just showcases how to you can define your system declaratively.
The `config` argument is the *evaluated* final configuration of your system. You use it to refer to other parts of your configuration. For example, you might make one service depend on another's path:
```nix
myService.dataPath = config.services.otherService.dataPath;
```
It's primarily used for referencing options *within* the configuration.
## The Module System
NixOS uses a powerful *module system*. A module is a Nix expression that declares:
- **`options`**: What configurable parameters this module exposes.
- **`config`**: How this module sets those parameters (and potentially other system parameters).
- **`imports`**: Other modules to include.
When you build your NixOS configuration using `nixos-rebuild switch --flake path/to/flake/directory#your-pc`, NixOS collects all the options and configurations from all activated modules, merges them, and then builds a new system closure in the Nix store.
## Searching NixOS Options
There are thousands of options in NixOS. You can search them in the [NixOS Options Search](https://search.nixos.org/options?channel=unstable).
For example, search for `services.desktopManager` to list all options regarding desktop managers.
## Home Manager
While NixOS manages system-wide configurations, **Home Manager** applies the power of Nix to your *user-specific* configuration files and dotfiles. Instead of manually symlinking dotfiles or writing install scripts, you define your user environment declaratively in Nix. Home Manager applies Nix's declarative power to the user space, much like NixOS does for the system space.
Let's extend our `flake.nix`:
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
home-manager.url = "github:nix-community/home-manager";
home-manager.inputs.nixpkgs.follows = "nixpkgs";
};
outputs =
{
self,
nixpkgs,
home-manager,
...
}@inputs:
let
inherit (self) outputs;
in
{
nixosConfigurations = {
your-pc = nixpkgs.lib.nixosSystem {
specialArgs = {
inherit inputs outputs;
};
modules = [ ./configuration.nix ];
};
};
homeConfigurations = {
your-user = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
extraSpecialArgs = {
inherit inputs outputs;
};
modules = [ ./home.nix ];
};
};
};
}
```
`home.nix` might look like this:
```nix
# home.nix
{ config, pkgs, ... }:
{
# Define your user's home directory
home.username = "youruser";
home.homeDirectory = "/home/youruser";
# Install user-specific packages
home.packages = with pkgs; [
htop
cowsay
];
# Configure zsh
programs.zsh.enable = true;
programs.zsh.ohMyZsh.enable = true;
programs.zsh.ohMyZsh.plugins = [ "git" "history" ];
# Git configuration
programs.git = {
enable = true;
userName = "Your Name";
userEmail = "your.email@example.com";
};
# ... many more options for things like VS Code, Tmux, themes, fonts etc.
}
```
You could now build your Home Manager configuration with `home-manager switch --flake path/to/flake/directory#your-user`.
Search for Home Manager options in the [Home Manager Options Search](https://home-manager-options.extranix.com/?release=master).
## What synix does
The [`synix` repository](https://git.sid.ovh/sid/synix) attempts to automate your NixOS and Home Manager experience. It exposes NixOS and Home Manager modules that sit on top of the already existing modules in NixOS and Home Manager respectively. Module options are added and opinionated defaults are set to get your configuration running with less configuration options needed to be set.
Create your NixOS and Home Manager configuration flake (we call that `nix-config`) with synix as an input using a template provided in the repository. Adding NixOS and Home Manager configurations is automated through a shell script. You can choose between some configuration templates for server or client systems. The installation process is automated through a shell script as well. Also, an installation guide is provided. Rebuilding your NixOS and Home Manager configurations is wrapped in synix's rebuild script.
The [Getting Started Guide](../getting-started/create-nix-config.md) will take you from nothing to a working NixOS configuration using synix.

BIN
docs/introduction-to-nix/nixpkgs-firefox.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 114 KiB

84
docs/introduction-to-nix/nixpkgs.md Normal file
View file

@ -0,0 +1,84 @@
# Nixpkgs
`Nixpkgs` is the massive collection of Nix expressions that define essentially *all* software available for Nix. It's the standard library for Nix, containing tens of thousands of packages. When you interact with `nixpkgs` in your Nix expressions, you're using this vast resource.
## How to Get Packages from Nixpkgs
The simplest way to use a package from Nixpkgs is to import it:
```bash
nix eval --impure --expr 'with import <nixpkgs> {}; pkgs.hello'
```
This evaluates an expression that imports Nixpkgs and makes its contents available as `pkgs`. The result will be a Nix store path for the `hello` package derivation.
You can also use `nix build`:
```bash
nix build nixpkgs#hello
```
This will build and symlink `hello` into your current directory as `result`.
And `nix run`:
```bash
nix run nixpkgs#hello/bin/hello
```
```
Hello, world!
```
> You could also run `./result/bin/hello`.
This command tells Nix to run the `hello` executable from the `hello` package in Nixpkgs.
## Searching Nixpkgs
You can search for packages directly from your terminal:
```bash
nix search nixpkgs firefox
```
This command will list all packages in your Nixpkgs channel that contain "firefox" in their name or description. You'll likely see results like `firefox` and `firefox-bin`.
However, the CLI is slow and not convenient to use. You should use the [Nixpkgs search](https://search.nixos.org/packages?channel=unstable) instead.
This is the entry of Firefox in Nixpkgs:
![Firefox in Nixpkgs](./nixpkgs-firefox.png)
### How to install *firefox*?
You can use Nix as a traditional package manager:
```bash
nix-env -iA nixpkgs.firefox
```
This is **not recommended** as packages installed this way must be updated and maintained by the user in the same way as with a traditional package manager. To temporarily install a package for testing purposes, use `nix-shell` instead:
```bash
nix-shell -p firefox
```
This will spawn a shell with `firefox` available. To permanently install a package with Nix, add it to your NixOS or Home Manager configuration. NixOS and Home Manager will be covered later in this guide.
## `pkgs.lib` utility functions
The `pkgs` argument (or `nixpkgs` itself) isn't just a list of applications; it also provides a powerful utility library called `pkgs.lib`. This library contains helper functions for working with Nix expressions, strings, lists, and more.
Many of these functions are used extensively within Nixpkgs itself to define packages and modules. You can browse the full [`pkgs.lib` documentation online](https://nixos.org/manual/nixpkgs/stable/#sec-functions-library) for more details.
## The Nixpkgs GitHub Repository
Nixpkgs is an open-source project hosted on GitHub: [github.com/NixOS/nixpkgs](https://github.com/NixOS/nixpkgs). You can explore its source code to see how packages are defined. Every package definition is a Nix expression!
For example, you could find the definition for `hello` at `pkgs/by-name/he/hello/package.nix`. It uses `stdenv.mkDerivation` just like our example.
## Binary Caches
Building everything from source every time can be slow. Nix solves this with **binary caches**. When someone builds a derivation, if that exact derivation (with its exact hash) has already been built and uploaded to a binary cache (like [`cache.nixos.org`](https://cache.nixos.org/)), Nix will simply *download* the pre-built binaries from the cache instead of building it locally.
This is possible because of the unique hashing of store paths. If the hash matches, the content *must* be identical, so a downloaded binary is guaranteed to be the same as one built locally. This significantly speeds up package installation and system updates.

9
docs/introduction-to-nix/overview.md Normal file
View file

@ -0,0 +1,9 @@
# Introduction to Nix
Welcome to the world of Nix! This guide aims to take you from a complete beginner to confidently using Nix for reproducible development environments and even managing your entire operating system with NixOS.
Nix is a powerful package manager that brings functional programming principles to system configuration. This means your builds are reproducible, changes are atomic, and rollbacks are easy. Forget "it works on my machine" – with Nix, it works everywhere.
We'll start with the fundamentals of the Nix language, then explore how Nix builds software. From there, we'll dive into the massive Nixpkgs collection, cover how Nix ensures reproducibility with flakes, and finally, show you how to manage your entire system with NixOS.
Let's begin!

10
docs/modules/home/bemenu.md Normal file
View file

@ -0,0 +1,10 @@
# bemenu
`bemenu` is a dynamic menu library and client program inspired by dmenu.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/bemenu).
If you use this repository's [Hyprland module](./hyprland.md), it is enabled by default.
## References
- [GitHub](https://github.com/Cloudef/bemenu)

17
docs/modules/home/common.md Normal file
View file

@ -0,0 +1,17 @@
# Common
The common module sets some opinionated defaults.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/common).
It is recommended to import it in your Home Manager configuration as some synix modules may depend on it:
```nix
{ inputs, ... }:
{
imports = [
inputs.synix.homeModules.common
];
}
```

65
docs/modules/home/gemini-cli.md Normal file
View file

@ -0,0 +1,65 @@
# Gemini CLI
An open-source AI agent that brings the power of Gemini directly into your terminal.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/gemini-cli).
## References
- [GitHub](https://github.com/google-gemini/gemini-cli)
- [CLI Docs](https://github.com/google-gemini/gemini-cli/tree/main/docs/cli)
## Setup
The package must be set by you. Easiest option is to use the synix overlay:
```nix
{ inputs, pkgs, ... }:
{
imports = [
inputs.synix.homeModules.gemini-cli
];
programs.gemini-cli = {
enable = true;
package = pkgs.synix.gemini-cli;
};
}
```
Gemini CLI reads environment variables, such as your API key, from `~/.gemini/.env`. You can manage it with sops-nix:
```nix
{ config, ... }:
{
sops.secrets.gemini-api-key = { };
sops.templates.gemini-cli-env = {
content = ''
GEMINI_API_KEY=${config.sops.placeholder.gemini-api-key}
'';
path = config.home.homeDirectory + "/.gemini/.env";
};
}
```
Set `gemini-api-key` in your `secrets.yaml`:
> Replace `abc123` with your Gemini API key.
```yaml
gemini-api-key: abc123
```
## Troubleshooting
These are some common warnings and errors you might encounter when using Gemini CLI:
### Error saving user settings file
```
Error saving user settings file: Error: EROFS: read-only file system, open '/home/you/.gemini/settings.json'
```
This is intended behavior.

51
docs/modules/home/gpg.md Normal file
View file

@ -0,0 +1,51 @@
# GPG
This module sets some defaults for gpg, mainly to let your gpg-agent handle ssh keys.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/gpg).
## SSH Setup
### GPG
You need a GPG authentication subkey. Follow the steps below to create one. If you already have a GPG key, skip to step 2.
#### 1. Generate a new GPG key
```sh
gpg --full-gen-key --allow-freeform-uid
```
1. Select `1` as the type of key.
1. Select `4096` for the keysize.
1. Select `0` to choose 'Never expire'.
1. Enter your name, email address, and a comment (if you want). Select `0` for 'Okay'.
#### 2. Create an authentication subkey
```sh
gpg --expert --edit-key KEY-ID
```
1. At the new `gpg>` prompt, enter: `addkey`
1. When prompted, enter your passphrase.
1. When asked for the type of key you want, select: (8) RSA (set your own capabilities).
1. Enter `S` to toggle the ‘Sign’ action off.
1. Enter `E` to toggle the ‘Encrypt’ action off.
1. Enter `A` to toggle the ‘Authenticate’ action on. The output should now include Current allowed actions: Authenticate, with nothing else on that line.
1. Enter `Q` to continue.
1. When asked for a keysize, choose `4096`.
1. Select `0` to choose 'Never expire'.
1. Once the key is created, enter `quit` to leave the gpg prompt, and `y` at the prompt to save changes.
### HM config
```nix
imports = [
inputs.synix.homeModules.gpg
];
services.gpg-agent.sshKeys = [ "YOUR_AUTH_SUBKEY_KEYGRIP" ];
```
> Get the keygrip of your authentication subkey with: `gpg -K --with-keygrip`

153
docs/modules/home/hyprland.md Normal file
View file

@ -0,0 +1,153 @@
# Hyprland
This module extends the options of and sets some defaults for [Hyprland](https://hyprland.org/):
- XDG Desktop Portal for screen sharing on Wayland
- XDG mime support and user directories
- enable Waybar as status bar
- enable dunst as notification service
- some [packages](https://git.sid.ovh/sid/synix/blob/master/modules/home/hyprland/packages.nix)
- [keybindings](https://git.sid.ovh/sid/synix/blob/master/modules/home/hyprland/binds/default.nix)
- manage default applications via the new `applications` option
> Always import both NixOS and Home Manager modules from `synix` when using Hyprland.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/hyprland).
## Keybindings
The ["Master Layout"](https://wiki.hyprland.org/Configuring/Master-Layout/) is the only supported window layout.
> `$mod`, `modifier` or `SUPER` refer to the same key which is the Windows key by default.
Keybinding | Function
---|---
`SUPER SHIFT c` | Kill active window
`SUPER 0..9` | Focus workspace 1-10 (`0` maps to workspace 10)
`SUPER SHIFT 0..9` | Move active window to workspace 1-10
`SUPER CTRL 0..9` | Focus workspace 1-10 on active monitor (moves if necessary)
`SUPER Tab` | Focus previous workspace on active monitor
`SUPER SHIFT Tab` | Move active window to previous workspace on active monitor
`SUPER Comma` | Focus left monitor
`SUPER Period` | Focus right monitor
`SUPER SHIFT Comma` | Move active workspace to left monitor
`SUPER SHIFT Period` | Move active workspace to right monitor
`SUPER SHIFT Return` | Make active window master
`SUPER CTRL Return` | Focus master window
`SUPER j` | Focus next window
`SUPER k` | Focus previous window
`SUPER SHIFT j` | Swap active window with the next window
`SUPER SHIFT k` | Swap active window with the previous window
`SUPER h` | Decrease horizontal space of master stack
`SUPER l` | Increase horizontal space of master stack
`SUPER SHIFT h` | Shrink active window vertically
`SUPER SHIFT l` | Expand active window vertically
`SUPER i` | Add active window to master stack
`SUPER SHIFT i` | Remove active window from master stack
`SUPER o` | Toggle between left and top orientation
`SUPER Left` | Focus window to the left
`SUPER Right` | Focus window to the right
`SUPER Up` | Focus upper window
`SUPER Down` | Focus lower window
`SUPER SHIFT Left` | Swap active window with window to the left
`SUPER SHIFT Right` | Swap active window with window to the right
`SUPER SHIFT Up` | Swap active window with upper window
`SUPER SHIFT Down` | Swap active window with lower window
`SUPER f` | Toggle floating for active window
`SUPER CTRL f` | Toggle floating for all windows on workspace
`SUPER SHIFT f` | Toggle fullscreen for active window
`SUPER LMB` | Move window by dragging
`SUPER RMB` | Resize window by dragging
Some [media keys](https://git.sid.ovh/sid/synix/blob/master/modules/home/hyprland/binds/mediakeys.nix) are also supported.
## Default applications
For clarification purposes, let's define the following terms:
- `<application>`: The literal name of the application/program. For example, `firefox`.
- `<category>`: The category of the application. For example, `browser`.
- `<exec-field-code>`: Available options are listed [here](https://specifications.freedesktop.org/desktop-entry-spec/latest/exec-variables.html). For example, `%U`.
To add default applications to Hyprland, you need to do the following steps:
### 1. Look for an existing category
Check if a fitting category for your application exists in [`applications/default.nix`](https://git.sid.ovh/sid/synix/blob/master/modules/home/hyprland/applications/default.nix).
Categories are listed under `options.wayland.windowManager.hyprland.applications`, for example:
```nix
# ...
emailclient = mkAppAttrs {
default = "thunderbird";
bind = [ "$mod, m, exec, ${emailclient}" ];
};
filemanager = mkAppAttrs {
default = "lf";
bind = [ "$mod, e, exec, ${terminal} -T ${filemanager} -e ${filemanager}" ];
windowRule = [
"float, title:^${filemanager}$"
"size 50% 50%, title:^${filemanager}$"
];
};
# ...
```
If no fitting category exists, create a new one and assign a default application with optional binds and window rules.
### 2. Create a directory to configure the application in
```nix
# applications/<application>/default.nix
{ inputs, outputs, config, lib, pkgs, ... }:
with lib;
let
cfg = config.wayland.windowManager.hyprland;
app = cfg.applications.<category>;
in
{
imports = [
# Import a module if available.
outputs.homeModules.<application> # or `inputs.synix.homeModules.<application>`
];
config = mkIf (cfg.enable && app == "<application>") {
programs.<application> = {
enable = true;
# Add more config here if needed.
};
# Define a desktop entry if the app's module or package does not ship with one
xdg.desktopEntries.<application> = {
name = "<application>"; # Use capital letters. For example, "Firefox".
genericName = "<category>"; # Be a bit more specific. For example, "Web Browser".
exec = "<application> <exec-field-code>"; # Program to execute, possibly with arguments.
terminal = false; # Whether the program runs in a terminal window.
mimeType = [ "<mime1>" "<mime2>" ]; # The MIME type(s) supported by this application. For example, "text/html".
};
};
}
```
> The function [`genMimeAssociations`](https://git.sid.ovh/sid/synix/blob/master/modules/home/hyprland/applications/genMimeAssociations.nix) might be useful here. See [`feh`'s config](https://git.sid.ovh/sid/synix/blob/master/modules/home/hyprland/applications/feh/default.nix) as an example.
> Available MIME types can be found [here](https://www.iana.org/assignments/media-types/media-types.xhtml).
### 3. Import the directory
You then need to import this directory in [`applications/default.nix`](https://git.sid.ovh/sid/synix/blob/master/modules/home/hyprland/applications/default.nix).
Look for the comment `# add your application directories here`:
```nix
# applications/default.nix
imports = [
./lf
./thunderbird
# add your application directories here
];
```

10
docs/modules/home/kitty.md Normal file
View file

@ -0,0 +1,10 @@
# Kitty
`kitty` is a cross-platform, fast, feature-rich, GPU based terminal emulator.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/kitty).
If you use this repository's [Hyprland module](./hyprland.md), it is enabled by default.
## References
- [GitHub](https://github.com/kovidgoyal/kitty)

11
docs/modules/home/lf.md Normal file
View file

@ -0,0 +1,11 @@
# lf
> Note: This module is not actively maintained. Expect things to break!
`lf` is a terminal file manager.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/lf).
## References
- [GitHub](https://github.com/gokcehan/lf)

10
docs/modules/home/networkmanager-dmenu.md Normal file
View file

@ -0,0 +1,10 @@
# networkmanager-dmenu
networkmanager-dmenu allows you to control NetworkManager via dmenu.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/networkmanager-dmenu).
If you use this repository's [Hyprland module](./hyprland.md), it is enabled by default.
## References
- [GitHub](https://github.com/firecat53/networkmanager-dmenu)

75
docs/modules/home/nextcloud-sync.md Normal file
View file

@ -0,0 +1,75 @@
# Nextcloud sync client
Because every other client sucks.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/nextcloud-sync).
## Setup
This is an example home config:
```nix
{ inputs, config, ... }:
{
imports = [
inputs.synix.homeModules.nextcloud-sync
];
services.nextcloud-sync = {
enable = true;
remote = "cloud.sid.ovh"; # just the URL without `https://`
passwordFile = config.sops.secrets.nextcloud.path;
connections = [ # absolute paths without trailing /
{
local = "/home/sid/aud";
remote = "/aud";
}
{
local = "/home/sid/doc";
remote = "/doc";
}
{
local = "/home/sid/img";
remote = "/img";
}
{
local = "/home/sid/vid";
remote = "/vid";
}
];
};
}
```
## Usage
You can manually sync by running:
```bash
nextcloud-sync-all
```
This will synchronize all defined connections.
## Troubleshooting
Each listed connection spawns a systemd user service and timer. Using the example above, we get:
```plaintext
nextcloud-sync-aud.service
nextcloud-sync-aud.timer
nextcloud-sync-doc.service
nextcloud-sync-doc.timer
nextcloud-sync-img.service
nextcloud-sync-img.timer
nextcloud-sync-vid.service
nextcloud-sync-vid.timer
```
Check their status to know what might go wrong:
```bash
systemctl --user status nextcloud-sync-doc.service
journalctl --user -xeu nextcloud-sync-doc.service
```

97
docs/modules/home/nixvim.md Normal file
View file

@ -0,0 +1,97 @@
# Nixvim
This module provides some defaults to quickly set up Nixvim with some plugins.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/nixvim).
## Config
Here is an example configuration:
```nix
# flake.nix
inputs = {
nixvim.url = "github:nix-community/nixvim";
nixvim.inputs.nixpkgs.follows = "nixpkgs";
};
```
```nix
# home/YOU/default.nix
{ inputs, lib, config, pkgs, ... }:
{
imports = [
inputs.synix.homeModules.stylix # This module works great with stylix
inputs.synix.homeMmodules.nixvim # You need to import this module
];
programs.nixvim = {
enable = true;
#colorschemes.SCHEME.enable = true; # If you do not use the stylix module, set a scheme manually
# This module provides defaults for the following plugins.
# They are all enabled by default.
plugins = {
cmp.enable = true; # Auto completion
dap.enable = true; # Debugging
lsp.enable = true; # Language server
lualine.enable = true; # Statusline
luasnip.enable = true; # Coding snippets
markdown-preview.enable = true; # Markdown preview in Browser
telescope.enable = true; # Fuzzy finder
treesitter.enable = true; # Syntax highlighting
trouble.enable = true; # Diagnostic messages
};
};
stylix = {
enable = true;
scheme = "dracula"; # This automatically sets the nixvim scheme as well
};
}
```
## Keymaps
This module sets some keymaps. Here are some important ones:
> `<leader>` defaults to the space key
key | action
---|---
`<leader>pv` | ex command (file explorer)
`<leader>s` | search and replace
`<C-a>` | select whole buffer
`<leader>ss` | toggle spell checking
`<leader>se` | switch to english spell checking
`<leader>sg` | switch to german spell checking
`z=` | correction suggestions for a misspelled word
`zg` | add word to spell list
`<C-CR>` | confirm selection in completion menu
`<Tab>` | select next item in completion menu
`<S-Tab>` | select previous item in completion menu
`gd` | go to definition
`K` | display more information about word under cursor
`<leader>bl` | list buffers
`<C-S-J>` | next buffer
`<C-S-K>` | previous buffer
`<leader>fb` or `<C-e>` | open file browser
`<leader>ff` | find files by name
`<leader>fg` or `<C-f>` | find files containing string
`<leader>xd` | toggle diagnostics
`<leader>xq` | toggle quick fix list
`<leader>m` | run make command
`<leader>xl` | toggle loclist list
`<leader>xx` | toggle diagnostics list
`<leader>xq` | toggle quifick list
`<C-A-J>` | previous quickfix item
`<C-A-K>` | next quickfix item
`<leader>ca` | apply code action
See [keymaps.nix](https://git.sid.ovh/sid/synix/blob/master/modules/home/nixvim/keymaps.nix) and [plugins](https://git.sid.ovh/sid/synix/blob/master/modules/home/nixvim/plugins/) for more details.
These commands do not have keymaps yet but might be useful anyway:
command | action
---|---
`:MarkdownPreview` | live render the current markdown buffer

84
docs/modules/home/password-manager.md Normal file
View file

@ -0,0 +1,84 @@
# Password Manager
This module will automatically install [`pass`](https://www.passwordstore.org/) as your password manager. It also provides a custom version of [`passmenu`](https://git.zx2c4.com/password-store/tree/contrib/dmenu/passmenu) using `bemenu` for Wayland sessions called `passmenu-bemenu` and configures [passff](https://codeberg.org/PassFF/passff) for your web browser.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/password-manager).
## Setup
It is assumed that you have a GPG key.
### HM config
```nix
imports = [
inputs.synix.homeModules.passwordManager
];
programs.passwordManager = {
enable = true;
key = "YOUR_GPG_KEYGRIP";
wayland = true; # if you are using Wayland
};
```
> Get your keygrip with `gpg -K --with-keygrip`
### Password Store
`pass` uses a Password Store to manage your password files. If this is your first time using `pass`, follow option _a)_. If you already have a remote git repository to store your password-store, follow option _b)_.
#### a) Initialize a new Password Store
Read the introduction and setup guide on the [pass home page](https://passwordstore.org).
#### b) Cloning your remote password-store repository
The following guide assumes that you have your private GPG key on a luks encrypted USB partition which is needed to access your remote repo through ssh.
1. **Identify the USB device**:
Identify the device name for your USB drive using the `lsblk` or `fdisk -l` command.
```bash
lsblk
```
Look for the device corresponding to your USB drive (e.g., `/dev/sdb1`).
2. **Unlock the LUKS partition**:
Unlock the LUKS partition with the `cryptsetup luksOpen` command. Replace `/dev/sdX1` with the actual device name of your USB partition.
```bash
sudo cryptsetup luksOpen /dev/sdX1 crypt
```
You will be prompted to enter the passphrase for the LUKS partition.
3. **Mount the unlocked partition**:
Mount the unlocked LUKS partition to access the files.
```bash
sudo mount /dev/mapper/crypt /mnt
```
4. **Import the GPG key**:
Use the `gpg --import` command to import the GPG key from the mounted USB partition.
```bash
gpg --import /mnt/path/to/privatekey.gpg
```
5. **Unmount and close the LUKS partition**:
After importing the key, unmount the partition and close the LUKS mapping.
```bash
sudo umount /mnt
sudo cryptsetup luksClose crypt
```
6. **Clone your password store repository**:
Clone your password store repository using the `git clone` command, for example:
```bash
git clone ssh://example.tld:/home/you/git/password-store.git ~/.local/share/password-store
```

99
docs/modules/home/sops.md Normal file
View file

@ -0,0 +1,99 @@
# Sops
For more information on how to use this module, see the [Sops NixOS module documentation](../nixos/sops.md).
For extensive documentation, read the [Readme on GitHub](https://github.com/Mic92/sops-nix/blob/master/README.md).
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/sops).
## 1. Generate an age key
```bash
mkdir -p ~/.config/sops/age
age-keygen -o ~/.config/sops/age/keys.txt
```
> Take note of your public key. You can print it again with:
> `age-keygen -y ~/.config/sops/age/keys.txt`
## 2. Edit `.sops.yaml`
This file manages access to all secrets in this repository (NixOS and Home Manager configurations).
```bash
vim ~/.config/nixos/.sops.yaml
```
Add your public key under `keys` and set creation rules for your config:
```yaml
keys:
- &you age12zlz6lvcdk6eqaewfylg35w0syh58sm7gh53q5vvn7hd7c6nngyseftjxl
creation_rules:
- path_regex: users/you/home/secrets/secrets.yaml$
key_groups:
- age:
- *you
```
## 3. Create a `secrets` directory
This directory in your Home Manager configuration will hold your secrets and sops configuration.
```bash
mkdir -p ~/.config/nixos/users/$(whoami)/home/secrets
```
## 4. Create a sops file
A sops file contains secrets in plain text. This file will then be encrypted with age. Make sure to follow the path regex in the creation rules.
```bash
cd ~/.config/nixos
sops users/$(whoami)/home/secrets/secrets.yaml
```
```yaml
# Files must always have a string value
example-key: example-value
# Nesting the key results in the creation of directories.
myservice:
my_subdir:
my_secret: password1
```
## 5. Deploy the secrets to the Nix store
Define your secrets under `sops.secrets`.
```bash
vim ~/.config/nixos/users/$(whoami)/home/secrets/default.nix
```
```nix
{
sops.secrets.example-key = {};
sops.secrets."myservice/my_subdir/my_secret" = {};
}
```
## 6. Reference secrets in your Home Manager configuration
Now you can use these secrets in your Home Manager configuration:
```nix
{ outputs, ... }:
{
imports = [
./secrets
outputs.homeModules.sops # includes all necessary configuration for sops-nix
];
someOption.secretFile = config.sops.secrets.example-key.path;
anotherOption.passwordFile = config.sops.secrets."myservice/my_subdir/my_secret".path;
}
```

90
docs/modules/home/stylix.md Normal file
View file

@ -0,0 +1,90 @@
# Stylix
This module wraps [stylix](https://github.com/nix-community/stylix), a theming framework for NixOS, Home Manager, nix-darwin, and Nix-on-Droid.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/stylix).
## References
- [docs](https://nix-community.github.io/stylix/)
## Usage
Add stylix to your flake inputs:
```nix
inputs = {
stylix.url = "github:nix-community/stylix";
stylix.inputs.nixpkgs.follows = "nixpkgs";
};
```
For example, in your home configuration, set:
```nix
imports = [ inputs.synix.homeModules.stylix ];
stylix = {
enable = true;
scheme = "SCHEME";
};
```
Replace `SCHEME` with the name of your scheme. Available schemes are listed as `validSchemes` in [our stylix module](https://git.sid.ovh/sid/synix/tree/master/modules/home/stylix/default.nix).
## Create a scheme
You can create your own scheme in `schemes/<scheme>.yaml`. To make it available via `stylix.scheme`, you need to add it to `validSchemes` and `customSchemes` in [the module's `default.nix`](https://git.sid.ovh/sid/synix/tree/master/modules/home/stylix/default.nix). Make sure that the resulting scheme name is a valid [colorscheme in nixvim](https://github.com/nix-community/nixvim/tree/main/plugins/colorschemes).
It is recommended to set colors according to their purpose / name. This means that `base00` should always be a rather dark color for the background and `base08` a reddish color.
```yaml
# <scheme>.yaml
system: "base16"
name: "SCHEME"
author: "AUTHOR"
description: "A dark theme inspired by the SCHEME color scheme."
slug: "SCHEME-theme"
variant: "dark"
palette:
base00: "080808" # background
base01: "323437" # alternate background
base02: "9e9e9e" # selection background
base03: "bdbdbd" # comments
base04: "b2ceee" # alternate text
base05: "c6c6c6" # default text
base06: "e4e4e4" # light foreground
base07: "eeeeee" # light background
base08: "ff5454" # error / red
base09: "cf87e8" # urgent / orange
base0A: "8cc85f" # warning / yellow
base0B: "e3c78a" # green
base0C: "79dac8" # cyan
base0D: "80a0ff" # blue
base0E: "36c692" # magenta
base0F: "74b2ff" # brown
```
Refer to [Stylix's style guide](https://stylix.danth.me/styling.html) for more information on where and how these colors will be used.
You can preview your color schemes with the [base16-viewer](https://sesh.github.io/base16-viewer/) (*Disable your dark reader*) or `print-colors` - a Python script to view color schemes in the terminal:
```bash
print-colors PATH/TO/colors.yaml
```
## Wallpaper
You can set a wallpaper with:
```nix
stylix.image = ./path/to/wallpaper.png;
```
This can be any image as a PNG file. You might want to take a look at [some Nix themed wallpapers](https://github.com/NixOS/nixos-artwork/tree/master/wallpapers) or [nix-wallpaper](https://github.com/lunik1/nix-wallpaper/tree/master) to create your own wallpaper with the Nix logo and custom colors.
Or create a solid color image with:
```bash
convert -size 3840x2160 "xc:#080808" wallpaper.png
```

11
docs/modules/home/virtualisation.md Normal file
View file

@ -0,0 +1,11 @@
# Virtualisation
Home Manager module to go with the [Virtualisation NixOS module](../nixos/virtualisation.md).
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/virtualisation).
## Setup
1. Import this module in your Home Manager configuration and the corresponding [NixOS module](../nixos/virtualisation.md) in your NixOS configuration.
1. Rebuild and reboot: `rebuild all && sudo reboot now`
1. Start the default network: `virsh net-autostart default`

10
docs/modules/home/waybar.md Normal file
View file

@ -0,0 +1,10 @@
# Waybar
Waybar is a highly customizable Wayland bar for Sway and Wlroots based compositors.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/waybar).
If you use this repository's [Hyprland module](./hyprland.md), it is enabled by default.
## References
- [GitHub](https://github.com/Alexays/Waybar)

13
docs/modules/home/yazi.md Normal file
View file

@ -0,0 +1,13 @@
# yazi
Terminal file manager written in Rust.
View the [*synix* Home Manager module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/home/yazi).
If you use this repository's [Hyprland module](./hyprland.md), it is enabled by default.
## References
- [GitHub](https://github.com/sxyazi/yazi)
- [docs](https://yazi-rs.github.io/docs/quick-start)
- [default keybindings](https://github.com/sxyazi/yazi/blob/shipped/yazi-config/preset/keymap-default.toml)
- [Plugins in Nixpkgs](https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=yaziPlugins)

9
docs/modules/nixos/audio.md Normal file
View file

@ -0,0 +1,9 @@
# Audio
PipeWire is a server for handling audio, video streams, and hardware on Linux.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/audio).
## References
- [Homepage](https://pipewire.org/)

90
docs/modules/nixos/baibot.md Normal file
View file

@ -0,0 +1,90 @@
# Baibot
Baibot is a Matrix AI bot.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/baibot).
## References
- [GitHub](https://github.com/etkecc/baibot)
## Setup
### Configuration
Since baibot's configuration file requires setting secrets as plain text strings, configuring the baibot service through Nix is not supported. You have to create a configuration file on your machine and point to it with `services.baibot.configFile`.
Use the [template configuration file](https://github.com/etkecc/baibot/blob/main/etc/app/config.yml.dist) for reference.
### User Creation
Create the `baibot` user on your Matrix instance. If you are using the [synix Matrix module](./matrix-synapse.md), this can be done with the `register_new_matrix_user` alias:
```bash
register_new_matrix_user
```
Set the `user localpart` and `password` according to your configuration.
Restart both `matrix-synapse.service` and `baibot.service`. You can then invite Baibot to any room you like.
### OpenAI API
Send this message in a room where Baibot has joined:
```
!bai agent create-global openai openai
```
The bot will reply with a YAML configuration which you need to edit and send back:
```yaml
base_url: https://api.openai.com/v1
api_key: YOUR_API_KEY_HERE
text_generation:
model_id: gpt-4o
prompt: 'You are a brief, but helpful bot called {{ baibot_name }} powered by the {{ baibot_model_id }} model. The date/time of this conversation''s start is: {{ baibot_conversation_start_time_utc }}.'
temperature: 1.0
max_response_tokens: 16384
max_context_tokens: 128000
speech_to_text:
model_id: whisper-1
text_to_speech:
model_id: tts-1-hd
voice: onyx
speed: 1.0
response_format: opus
image_generation:
model_id: dall-e-3
style: vivid
size: 1024x1024
quality: standard
```
Set `openai` as the default for any purpose you like:
```
!bai config global set-handler text-generation global/openai
!bai config global set-handler speech-to-text global/openai
!bai config global set-handler text-to-speech global/openai
!bai config global set-handler image-generation global/openai
```
## Tips
### Set STT to Transcribe Only
```
!bai config global speech-to-text set-flow-type only_transcribe
```
### Set user access
```
!bai access set-users SPACE_SEPARATED_PATTERNS
```
> For example: `@*:example.com`
## Todo
1. Set up a local LLM for speech-to-text with Ollama.
1. Whitelist each user for the speech-to-text engine only.

25
docs/modules/nixos/cifsmount.md Normal file
View file

@ -0,0 +1,25 @@
# cifsMount
> Warning: This module is not actively maintained. Expect things to break!
This module allows you to automount cifs shares after the login of the specified user. The remote has to have a running samba server.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/cifsMount).
## Config
```nix
config.services.cifsMount = {
enable = true;
remotes = [
{
host = "ip_address";
shareName = "share_name";
mountPoint = "/home/user/mount_point";
credentialsFile = "/home/user/.smbcredentials";
user = "user";
}
# more remotes ...
];
};
```

17
docs/modules/nixos/common.md Normal file
View file

@ -0,0 +1,17 @@
# Common
The common module sets some opinionated defaults.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/common).
It is recommended to import it in your NixOS configuration as some synix modules may depend on it:
```nix
{ inputs, ... }:
{
imports = [
inputs.synix.nixosModules.common
];
}
```

20
docs/modules/nixos/device.md Normal file
View file

@ -0,0 +1,20 @@
# Device
This module lets you set some defaults for a device type.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/device).
Available devices are:
- desktop
- laptop
- server
- vm
To enable these defaults, you need to import this module in your host configuration. For example:
```nix
# hosts/HOSTNAME/default.nix
imports = [ inputs.synix.nixosModules.device.vm ]; # this imports all defaults for VMs. See `vm.nix`
```

7
docs/modules/nixos/ftp-webserver.md Normal file
View file

@ -0,0 +1,7 @@
# FTP web server
> Warning: This module is not actively maintained. Expect things to break!
This module sets up a simple ftp web server behind a reverse proxy (`ftp.domain.tld` by default).
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/ftp-webserver).

70
docs/modules/nixos/headplane.md Normal file
View file

@ -0,0 +1,70 @@
# Headplane
A feature-complete Web UI for Headscale.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/headplane).
## References
- [Website](https://headplane.net)
- [GitHub](https://github.com/tale/headplane)
- [NixOS options](https://headplane.net/NixOS-options)
## Sops
Provide the following entries to your `secrets.yaml`:
> Replace `abc123` with your actual secrets
```yaml
headplane:
cookie_secret: abc123
agent_pre_authkey: abc123
```
Generate your cookie secret with:
```bash
nix-shell -p openssl --run "openssl rand -hex 16"
```
Generate your agent pre-authkey with:
```bash
sudo headscale users create headplane-agent
sudo headscale users list # get headplane-agent user id
sudo headscale preauthkeys create --expiration 99y --reusable --user <HEADPLANE-AGENT-ID>
```
## Setup
Set a CNAME record for your Headplane subdomain (`headplane` by default) pointing to your domain.
## Config
```nix
# flake.nix
headplane.url = "github:tale/headplane";
headplane.inputs.nixpkgs.follows = "nixpkgs";
```
```nix
# configuration.nix
{
imports = [ inputs.synix.nixosModules.headplane ];
services.headplane = {
enable = true;
};
}
```
## Usage
Create a Headscale API key:
```bash
sudo headscale apikeys create
```
Visit the admin login page: `https://sub.domain.tld/admin/login`

58
docs/modules/nixos/headscale.md Normal file
View file

@ -0,0 +1,58 @@
# Headscale
Headscale is an open source, self-hosted implementation of the Tailscale control server.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/headscale).
## References
- [Website](https://headscale.net/stable/)
- [GitHub](https://github.com/juanfont/headscale)
- [Example configuration file](https://github.com/juanfont/headscale/blob/main/config-example.yaml)
## Setup
Set a CNAME record for your Headscale subdomain (`headscale` by default) pointing to your domain.
## Config
```nix
{
imports = [ inputs.synix.nixosModules.headscale ];
services.headscale = {
enable = true;
openFirewall = true;
};
}
```
## Usage
Create a new user:
```bash
sudo headscale users create <USER>
```
Get the user's id:
```bash
sudo headscale users list
```
Create a pre auth key for that user:
```bash
sudo headscale preauthkeys create --expiration 99y --reusable --user <ID>
```
Give the user the pre-auth key.
## Troubleshooting
Check if your ACL config is valid:
```bash
sudo headscale policy check --file PATH/TO/acl.hujson
```

26
docs/modules/nixos/i2pd.md Normal file
View file

@ -0,0 +1,26 @@
# I2P Daemon
I2P is an End-to-End encrypted and anonymous Internet.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/i2pd).
## References
- [Homepage](https://i2pd.website/)
- [Documentation](https://i2pd.readthedocs.io/en/latest/)
- [GitHub](https://github.com/PurpleI2P/i2pd)
- [I2P on NixOS guide](https://voidcruiser.nl/rambles/i2p-on-nixos/)
## Configuration
### NixOS
```nix
{ inputs, ... }:
{
imports = [ inputs.synix.nixosModules.i2pd ];
services.i2pd.enable = true;
}
```

30
docs/modules/nixos/jellyfin.md Normal file
View file

@ -0,0 +1,30 @@
# Jellyfin
Jellyfin is a free and open-source media server and suite of multimedia applications.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/jellyfin).
## References
[docs](https://jellyfin.org/docs/)
## Setup
Users, Plugins, and Libraries are managed in the web interface. You have to declare them manually.
Visit the web interface and follow the on screen instructions. Create libraries corresponding to `config.services.jellyfin.libraries`.
## Upload files
```bash
rsync -arvzP -e 'ssh -p SSH_PORT' LOCAL_PATH YOU@REMOTE:JELLYFIN_DATA_DIR/libraries/LIBRARY
```
> the user `YOU` has to be in the *jellyfin* group on the remote machine `REMOTE`
- `SSH_PORT`: Your SSH port
- `LOCAL_PATH`: Local path to your media file(s)
- `YOU`: Your user on your remote machine
- `REMOTE`: IP/domain of your remote machine
- `JELLYFIN_DATA_DIR`: `config.services.jellyfin.dataDir`
- `LIBRARY`: Target library. See `config.services.jellyfin.libraries`

9
docs/modules/nixos/jirafeau.md Normal file
View file

@ -0,0 +1,9 @@
# Jirafeau
Jirafeau is a project that allows "one-click filesharing", making it easy to upload a file and give it a unique link.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/jirafeau).
## References
- [docs](https://github.com/Newlode/jirafeauhttps://github.com/Newlode/jirafeau)

62
docs/modules/nixos/mailserver.md Normal file
View file

@ -0,0 +1,62 @@
# Mail
A simple NixOS mailserver.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/mailserver).
## References
- [docs](https://nixos-mailserver.readthedocs.io/en/latest/index.html)
## Setup
Follow the [setup guide](https://nixos-mailserver.readthedocs.io/en/master/setup-guide.html#setup-dns-a-record-for-server).
## Sops
Provide every user's hashed password to your host's `secrets.yaml`:
> Replace `abc123` with your actual secrets
```yaml
mailserver:
accounts:
user1: abc123
user2: abc123
# ...
```
Generate hashed passwords with:
```sh
nix-shell -p mkpasswd --run 'mkpasswd -sm bcrypt'
```
## Config
### `flake.nix`
```nix
inputs = {
nixos-mailserver.url = "gitlab:simple-nixos-mailserver/nixos-mailserver";
nixos-mailserver.inputs.nixpkgs.follows = "nixpkgs";
};
```
### Host configuration:
```nix
imports = [ inputs.synix.nixosModules.mailserver ]
mailserver = {
enable = true;
accounts = {
admin = {
aliases = [ "postmaster" ];
};
alice = { };
};
};
```
You may need to set [`mailserver.stateVersion`](https://nixos-mailserver.readthedocs.io/en/master/migrations.html). At the time of writing, you need to set it to `3`, but you should check the mailserver docs yourself.

144
docs/modules/nixos/matrix-synapse.md Normal file
View file

@ -0,0 +1,144 @@
# Matrix-Synapse
Synapse is a [Matrix](https://matrix.org/) homeserver. Matrix is an open network for secure, decentralised communication.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/matrix-synapse).
## References
- [Synapse repository](https://github.com/element-hq/synapse)
- [Synapse documentation](https://matrix-org.github.io/synapse/latest/welcome_and_overview.html)
- [Coturn repository](https://github.com/coturn/coturn)
- [Coturn example configuration](https://github.com/coturn/coturn/blob/master/examples/etc/turnserver.conf)
## Setup
### DNS
Make sure you have a CNAME record for `turn` pointing to your machine running Coturn.
The fqdn is set by `services.coturn.realm`.
### Sops
Provide the following entries to your secrets.yaml:
> Replace `abc123` with your actual secret(s)
```yaml
coturn:
static-auth-secret: abc123
matrix:
registration-shared-secret: abc123
livekit:
key: abc123
```
Generate the livekit key with:
```bash
nix-shell -p livekit --run "livekit-server generate-keys | tail -1 | awk '{print $3}'"
```
## Config
[Coturn has its own module](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/matrix-synapse), making it easy to outsource to a small VPS with a static IPv4 address.
If you do so, both machines need the secret `coturn/static-auth-secret`.
In the following example, both services run on the same machine:
```nix
{
imports = [
inputs.synix.nixosModules.coturn
inputs.synix.nixosModules.matrix-synapse
];
networking.domain = "example.tld";
services.coturn = {
enable = true;
sops = true;
openFirewall = true;
};
services.matrix-synapse = {
enable = true;
sops = true;
coturn.enable = true;
# see below
bridges = {
whatsapp = {
enable = true;
admin = "@you:example.tld";
};
signal = {
enable = true;
admin = "@you:example.tld";
};
};
};
# You only need this if you want to use bridges
nixpkgs.config.permittedInsecurePackages = [
"olm-3.2.16"
];
}
```
## Bridges
> Warning: Bridges use [`mautrix-go`](https://github.com/mautrix/go) which relies on [deprecated `libolm`](https://github.com/mautrix/go/issues/262).
### Sops
Provide the following entries to your secrets.yaml:
> Replace `abc123` with your actual secret(s) and `BRIDGE` with the name of your bridge (e.g., `whatsapp` or `signal`)
```yaml
mautrix-BRIDGE:
encryption-pickle-key: abc123
provisioning-shared-secret: abc123
public-media-signing-key: abc123
direct-media-server-key: abc123
```
Generate the secrets with:
```bash
nix-shell -p openssl --run "openssl rand -base64 32"
```
### NixOS configuration
The `config.yaml` for each bridge is managed through `services.mautrix-BRIDGE.settings`:
- [services.mautrix-signal.settings](https://search.nixos.org/options?channel=unstable&query=services.mautrix-signal.settings): Generate an example config with: `mautrix-signal -c signal.yaml --generate-example-config`
- [services.mautrix-whatsapp.settings](https://search.nixos.org/options?channel=unstable&query=services.mautrix-whatsapp.settings): Generate an example config with: `mautrix-whatsapp -c whatsapp.yaml --generate-example-config`
### Authentication
1. Open chat with bridge bot: `@BOT:DOMAIN.TLD`
- WhatsApp: `whatsappbot`
- Signal: `signalbot`
1. Send: `login qr`
1. Scan QR code
1. Switch puppets: `login-matrix ACCESS_TOKEN`
- Get your token with: Settings > Help & About > Advanced > Access Token
## Administration
### Register users
```bash
register_new_matrix_user -u USERNAME -p PASSWORD
```
## Troubleshooting
### Bridges: Specified admin user is not an admin in portal rooms
There seems to be a bug that the user specified under `services.matrix-synapse.bridges.whatsapp.admin` does not have admin permissions in portal rooms. You can set the power level manually inside each portal room:
```plaintext
!wa set-pl @YOU:DOMAIN.TLD 100
```

99
docs/modules/nixos/maubot.md Normal file
View file

@ -0,0 +1,99 @@
# Maubot
A plugin-based Matrix bot system.
> Warning: Maubot uses [deprecated `libolm`](https://github.com/mautrix/go/issues/262).
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/maubot).
## References
- [GitHub repository](https://github.com/maubot/maubot)
## Sops
Provide the following entries to your host's `secrets.yaml`:
> Replace `abc123` with your actual secrets as well as `alice` and `bob` with your actual admin user names.
```yaml
maubot:
admins:
alice: abc123
bob: abc123
# ...
```
## Config
This module only works if Matrix Synapse is running on the same machine.
See [the module on synix](./matrix-synapse.md).
```nix
{
imports = [
inputs.synix.nixosModules.maubot
inputs.synix.nixosModules.matrix-synapse
];
nixpkgs.config.permittedInsecurePackages = [
"olm-3.2.16"
];
services.maubot = {
enable = true;
sops = true;
admins = [
"alice"
"bob"
];
plugins = with config.services.maubot.package.plugins; [
gitlab
reminder
];
};
services.matrix-synapse = {
enable = true;
# ...
};
}
```
## Setup
1. Create a bot: `$ register_new_matrix_user`
1. Login as your admin user: `$ mbc login`
1. Authenticate as bot: `$ mbc auth`
1. Take note of the access token and device ID
1. Visit `https:/EXAMPLE.TLD/_matrix/maubot`
1. Create a client (if not already preset)
1. Create an instance
## Bots
### GitLab
> See [Readme on GitHub](https://github.com/maubot/gitlab?tab=readme-ov-file)
Create a personal access token with full API access.
```
!gitlab server login https://git.example.com PERSONAL_ACCESS_TOKEN
!gitlab webhook add https://git.example.com user/project
```
Check the webhook URL for potential errors.
## Tips
### Upload a profile picture to Matrix
```sh
curl -X POST "https://YOUR_HOMESERVER_URL/_matrix/media/v3/upload" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: image/png" \
--data-binary "@/path/to/your/image.png"
```
The respond body contains a valid avatar URL (`mxc://...`).

48
docs/modules/nixos/mcpo.md Normal file
View file

@ -0,0 +1,48 @@
# mcpo
A simple MCP-to-OpenAPI proxy server.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/mcpo).
## References
- [GitHub](https://github.com/open-webui/mcpo)
## Configuration
You have to provide a package, for example from [synix](https://git.sid.ovh/sid/synix/tree/master/pkgs/mcpo/default.nix).
Setting `mcpServers` is required. The following example runs a NixOS MCP server using [mcp-nixos](https://github.com/utensils/mcp-nixos).
```nix
{ inputs, lib, pkgs, ... }:
let
inherit (pkgs.stdenv.hostPlatform) system;
in
{
imports = [ inputs.synix.nixosModules.mcpo ];
services.mcpo = {
enable = true;
package = inputs.synix.packages."${system}".mcpo;
settings = {
mcpServers = {
nixos = {
command = lib.getExe inputs.mcp-nixos.packages."${system}".mcp-nixos;
};
};
};
};
}
```
## Usage
Each tool will be accessible under its own unique route `127.0.0.1:8000/<mcp-server>`. Following the example from above, visit [127.0.0.1:8000/nixos/docs](http://127.0.0.1:8000/nixos/docs) to send requests manually.
## Open WebUI Integration
Follow the [official Open WebUI integration documentation starting at *Step 2*](https://docs.openwebui.com/openapi-servers/open-webui/#step-2-connect-tool-server-in-open-webui).
In Open WebUI, users have to set *Function Calling* to *Native* in *Settings* > *General* > *Advanced Parameters*. Then, they can enable MCP servers in a chat by clicking *More* (the plus sign) in the bottom left of the prompt window.

42
docs/modules/nixos/miniflux.md Normal file
View file

@ -0,0 +1,42 @@
# Miniflux
Miniflux is a minimalist and opinionated feed reader.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/miniflux).
## References
- [Website](https://miniflux.app/)
- [GitHub](https://github.com/miniflux/v2)
- [Configuration parameters](https://miniflux.app/docs/configuration.html)
## Setup
### DNS
Make sure you have a CNAME record for Miniflux's subdomain (`rss` by default) pointing to your domain.
### Sops
Provide the following entries to your secrets.yaml:
> Replace `abc123` with your actual secret(s)
```yaml
miniflux:
admin-password: abc123
```
## Config
```nix
{
imports = [inputs.synix.nixosModules.miniflux ];
services.miniflux = {
enable = true;
reverseProxy.enable = true;
reverseProxy.subdomain = "rss";
};
}
```

20
docs/modules/nixos/normalUsers.md Normal file
View file

@ -0,0 +1,20 @@
# Normal Users
This module automates user creation for normal users.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/normalUsers).
## Config
For example:
```nix
imports = [ inputs.synix.nixosModules.normalUsers ]
config.normalUsers = {
alice = {
extraGroups = [ "wheel" ];
sshKeyFiles = [ ../../users/alice/pubkeys/id_rsa.pub ];
};
};
```

25
docs/modules/nixos/nvidia.md Normal file
View file

@ -0,0 +1,25 @@
# Nvidia
NixOS module that configures your Nvidia GPU with proprietary drivers.
> Tested on Turing and Ampere. Should work with most modern Nvidia GPUs.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/nvidia).
## Setup
Import this module inside your NixOS configuration:
```
imports = [ inputs.synix.nixosModules.nvidia ];
```
## Config
Set the Nvidia package with `hardware.nvidia.package`. The default ist:
```nix
imports = [ inputs.synix.nixosModules.nvidia ];
hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.latest;
```

44
docs/modules/nixos/open-webui-oci.md Normal file
View file

@ -0,0 +1,44 @@
# Open WebUI OCI
Open WebUI is an extensible, self-hosted AI interface that adapts to your workflow, all while operating entirely offline.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/open-webui-oci).
## References
- [Homepage](https://openwebui.com/)
- [GitHub](https://github.com/open-webui/open-webui)
- [Environment Configuration](https://docs.openwebui.com/getting-started/env-configuration/)
## Configuration
```nix
{ inputs, ... }:
{
imports = [ inputs.synix.nixosModules.open-webui-oci ];
services.open-webui-oci.enable = true;
}
```
## Usage
Visit the web interface at your specified location to create an admin account.
> The default location is `http://127.0.0.1:8080`.
## Troubleshooting
### JSON parse error
If you get this error in the web interface:
```
SyntaxError: Unexpected token 'd', "data: {"id"... is not valid JSON category
```
Clear your browser cache. Steps on Chromium based browsers:
1. Open DevTools (F12) → Right-click refresh button
1. Click "Empty Cache and Hard Reload"

7
docs/modules/nixos/print-server.md Normal file
View file

@ -0,0 +1,7 @@
# Print server
> Note: This module is not actively maintained. Expect things to break!
This module sets up a printing server with a web interface.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/print-server).

66
docs/modules/nixos/radicale.md Normal file
View file

@ -0,0 +1,66 @@
# Radicale
A simple CalDAV and CardDAV server.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/radicale).
## References
- [Documentation](https://radicale.org/v3.html#documentation-1)
- [Wiki](https://github.com/Kozea/Radicale/wiki)
- [GitHub](https://github.com/Kozea/Radicale)
## Sops
Provide every user's SHA512 hashed password to your host's `secrets.yaml`:
> Replace `abc123` with your actual secrets
```yaml
radicale:
user1: abc123
user2: abc123
# ...
```
Generate hashed passwords with:
```sh
nix-shell -p openssl --run 'openssl passwd -6 <password>'
```
## Setup
Set a CNAME record for your Radicale subdomain (`dav` by default) pointing to your domain.
Add two SRV records:
Calendar:
- type: `SRV`
- name: `_caldavs._tcp`
- priority: `0`
- weight: `1`
- port: `443`
- target: `dav.domain.tld.`
Contacts:
- name: `_carddavs._tcp`
> rest as above
## Config
```nix
{ inputs, ... }:
{
imports = [ inputs.synix.nixosModules.radicale ];
services.radicale = {
enable = true;
users = [
"user1"
"user2"
];
};
}
```

11
docs/modules/nixos/rss-bridge.md Normal file
View file

@ -0,0 +1,11 @@
# RSS-Bridge
RSS-Bridge is a PHP web application. It generates web feeds for websites that don't have one.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/rss-bridge).
## References
- [docs](https://rss-bridge.github.io/rss-bridge/index.html)
- [repo](https://github.com/RSS-Bridge/rss-bridge)
- [bridges](https://github.com/RSS-Bridge/rss-bridge/tree/master/bridges)

58
docs/modules/nixos/sops.md Normal file
View file

@ -0,0 +1,58 @@
# Sops
Atomic secret provisioning for NixOS based on sops.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/sops).
## References
- [GitHub](https://github.com/Mic92/sops-nix)
## Setup
Generate an age key for your host from its ssh host key:
```bash
nix-shell -p ssh-to-age --run 'cat /etc/ssh/ssh_host_ed25519_key.pub | ssh-to-age'
```
Then, add it to `.sops.yaml` (see [usage example](https://github.com/Mic92/sops-nix?tab=readme-ov-file#usage-example)).
## Config
### Flake
```nix
# flake.nix
inputs = {
sops-nix.url = "github:Mic92/sops-nix";
sops-nix.inputs.nixpkgs.follows = "nixpkgs";
};
```
### Host configuration
Create a `secrets` directory in your hosts directory. Declare all your secrets in it:
```nix
# hosts/YOUR_HOST/secrets/default.nix
{ inputs, ... }:
{
imports = [ inputs.synix.nixosModules.sops ];
sops.secrets.your-secret = { };
sops.secrets.other-secret = { };
```
## Usage
For more information on how to use sops-nix, see the [Sops Home Manager module documentation](../home/sops.md).
## Update Keys
Update the keys of your SOPS files after making changes to `.sops.yaml`:
```bash
sops --config PATH/TO/.sops.yaml updatekeys PATH/TO/secrets.yaml
```

36
docs/modules/nixos/tailscale.md Normal file
View file

@ -0,0 +1,36 @@
# Tailscale
Private WireGuard networks made easy.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/tailscale).
## References
- [Website](https://tailscale.com/)
- [GitHub](https://github.com/tailscale/tailscale)
- [Documents](https://tailscale.com/kb/1017/install)
## Sops
Provide the following entries to your `secrets.yaml`:
> Replace `abc123` with your actual secrets
```yaml
tailscale:
auth-key: abc123
```
## Config
```nix
{
imports = [ inputs.synix.nixosModules.tailscale ];
services.tailscale = {
enable = true;
enableSSH = true;
loginServer = "<your-headscale-instance>";
};
}
```

172
docs/modules/nixos/virtualisation.md Normal file
View file

@ -0,0 +1,172 @@
# Virtualisation
Virtualisation using QEMU via libvirt and managed through Virt-manager with VFIO support.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/virtualisation).
## Overview
1. **QEMU** is the hypervisor that provides the core virtualisation capabilities.
1. **libvirt** is a toolkit and API that manages virtualisation platforms, such as QEMU.
1. **Virt-manager** is a GUI tool that interacts with libvirt to manage VMs.
1. **virsh** is a CLI tool that interacts with libvirt to manage VMs.
## Docs
### QEMU
- [Official docs](https://www.qemu.org/docs/master/)
### libvirt
- [Official docs](https://libvirt.org/docs.html)
- [Arch Wiki](https://wiki.archlinux.org/title/Libvirt)
- [virsh CLI](https://www.libvirt.org/manpages/virsh.html)
> If you are using the [Home Manager module](../home/virtualisation.md) as well, then `virsh` is aliased to `virsh --connect qemu:///system`
### Virt-manager
- [GitHub Repository](https://github.com/virt-manager/virt-manager)
- [NixOS Official Wiki](https://wiki.nixos.org/wiki/Virt-manager)
- [NixOS Community Wiki](https://nixos.wiki/wiki/Virt-manager)
- [Arch Wiki](https://wiki.archlinux.org/title/Virt-manager)
## Setup
1. Import this module in your NixOS config. It is recommended to use the [Virtualisation Manager module](../home/virtualisation.md) as well.
1. Add your user to the `libvirtd`, `qemu-libvirtd` and `kvm` group:
```nix
users.extraGroups.libvirtd.members = [ "<you>" ];
users.extraGroups.qemu-libvirtd.members = [ "<you>" ];
users.extraGroups.kvm.members = [ "<you>" ];
```
1. Rebuild and reboot: `rebuild all && sudo reboot now`
1. Enable and start the default network and reboot again: `virsh net-autostart default && virsh net-start default`
## VFIO
### Setup
For successful PCI device passthrough, devices must be properly isolated by IOMMU groups. A device can be safely passed through if:
- It is the **only device** in its IOMMU group (recommended), OR
- **All devices** in its IOMMU group are passed through together
This module includes an `iommu-groups` command to help identify IOMMU groups:
```bash
iommu-groups
```
In this example, IOMMU group 9 contains only the Nvidia GPU which will get passed to the VM:
```
IOMMU Group 9 01:00.0 3D controller [0302]: NVIDIA Corporation TU117M [GeForce GTX 1650 Mobile / Max-Q] [10de:1f9d] (rev a1)
```
Take not of the PCI device ID. In this case: `10de:1f9d`.
### Config
This is an example with the Nvidia GPU above:
```nix
{ inputs, ... }:
{
imports = [ inputs.synix.nixosModules.virtualisation ];
virtualisation = {
vfio = {
enable = true;
IOMMUType = "amd";
devices = [
"10de:1f9d"
];
blacklistNvidia = true;
};
hugepages.enable = true;
};
}
```
### Virt Manager
#### 1. Open VM Hardware Settings
- Select your VM in Virt Manager
- Click *"Show virtual hardware details"*
#### 2. Add PCI Host Device
- Click *"Add Hardware"* button at bottom
- Select *"PCI Host Device"* from the list
- Click *"Finish"*
You may repeat this process for as many devices as you want to add to your VM.
### Looking Glass with KVMFR
*This has not yet been tested.*
### Troubleshooting
#### Check Kernel Parameters
View current kernel parameters:
```bash
cat /proc/cmdline
```
Check VFIO-related parameters:
```bash
dmesg | grep -i vfio
```
Verify IOMMU is enabled:
```bash
dmesg | grep -i iommu
```
#### Verify device binding
```bash
lscpi -k
```
Look for your device you want to pass through. It should say:
```
Kernel driver in use: vfio-pci
```
For example:
```
01:00.0 3D controller: NVIDIA Corporation TU117M [GeForce GTX 1650 Mobile / Max-Q] (rev a1)
Subsystem: Lenovo Device 380d
Kernel driver in use: vfio-pci
Kernel modules: nvidiafb, nouveau
```
#### Verify module status
Ensure blacklisted modules are not loaded:
```bash
lsmod | grep nvidia
lsmod | grep nouveau
```
These should return nothing.
#### `vfio-pci.ids` not appearing
Check generated bootloader config:
```bash
cat /boot/loader/entries/nixos-*.conf
```

5
docs/modules/nixos/webpage.md Normal file
View file

@ -0,0 +1,5 @@
# Web Page
A very simple module to serve a static web page behind a reverse proxy using nginx.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/webPage).

33
docs/modules/nixos/windows-oci.md Normal file
View file

@ -0,0 +1,33 @@
# Windows OCI
Windows inside a Docker container.
View the [*synix* NixOS module on Forgejo](https://git.sid.ovh/sid/synix/tree/master/modules/nixos/windows-oci).
## References
- [dockur on GitHub](https://github.com/dockur/windows)
## Config
```nix
imports = [ inputs.synix.nixosModule.windows-oci ];
services.windows-oci.enable = true;
```
## Setup
You can monitor the installation process with:
```bash
journalctl -u podman-windows.service -f
```
The first-time setup may fail. Rebooting should resolve the issue.
## Usage
Access the VNC web interface at `http://127.0.0.1:8006`. Or connect via RDP at `127.0.0.1`.
TODO: Setup Windows RemoteApp

49
docs/tips/dependency-tracing.md Normal file
View file

@ -0,0 +1,49 @@
# Dependency Tracing
Dependency tracing in Nix allows you to understand the relationships between packages in your system configuration.
## Forward Path Tracing
This section answers the question: "*What are the dependencies of an installed package?*"
Print a store path's dependency tree with:
```bash
nix-store --query --tree /nix/store/...
```
Get a package's store path with:
> Replace `YOUR_CONFIG` with the name of your NixOS or Home Manager configuration, and `PACKAGE` with the name of the package you want to analyze.
##### NixOS
```bash
nix path-info ~/.config/nixos#nixosConfigurations.YOUR_CONFIG.pkgs.PACKAGE
```
##### Home Manager
```bash
nix path-info ~/.config/nixos#homeConfigurations.YOUR_CONFIG.pkgs.PACKAGE
```
## Backward Path Tracing
This section answers the question: "*What are parents of an installed package?*" or "*Why is a certain package installed?*"
Print a package's dependency path with:
> Replace `YOUR_CONFIG` with the name of your NixOS or Home Manager configuration, and `PACKAGE` with the name of the package you want to analyze.
##### NixOS
```bash
nix why-depends --derivation ~/.config/nixos#nixosConfigurations.YOUR_CONFIG.config.system.build.toplevel ~/.config/nixos#nixosConfigurations.YOUR_CONFIG.pkgs.PACKAGE
```
##### Home Manager
```bash
nix why-depends --derivation ~/.config/nixos#homeConfigurations.YOUR_CONFIG.activationPackage ~/.config/nixos#homeConfigurations.YOUR_CONFIG.pkgs.PACKAGE
```

23
docs/tips/useful-links.md Normal file
View file

@ -0,0 +1,23 @@
# Useful Links
A collection of links regarding Nix/NixOS.
## Documentation
- [Nix Pills](https://nixos.org/guides/nix-pills/): An introduction to Nix, ported to the current format.
- [NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/): An unofficial book for beginners.
- [Noogle](https://noogle.dev/): Search Nix functions.
- [nix-lib](https://teu5us.github.io/nix-lib.html): Nix (builtins) & Nixpkgs (lib) functions.
- [nix.dev](https://nix.dev/): Official documentation for the Nix ecosystem.
## Tools
- [NüschtOS search](https://github.com/NuschtOS/search): Simple and fast static-page NixOS option search.
- [compose2nix](https://github.com/aksiksi/compose2nix): Generate a NixOS config from a Docker Compose project.
- [manix](https://github.com/mlvzk/manix): A fast CLI documentation searcher for Nix.
- [nix-tree](https://github.com/utdemir/nix-tree): Interactively browse dependency graphs of Nix derivations.
- [tex2nix](https://github.com/rgri/tex2nix): Generate texlive nix expressions for documents.
## NixOS configurations
- [srvos](https://github.com/nix-community/srvos): NixOS profiles for servers.