To begin the installation, you have to boot your computer from the install drive.

The graphical installer is recommended for desktop users and will guide you through the installation.

NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI installation is broadly the same as for a BIOS installation. The differences are mentioned in the following steps.

The NixOS manual is available by running nixos-help in the command line or from the application menu in the desktop environment.

To have access to the command line on the graphical images, open Terminal (GNOME) or Konsole (Plasma) from the application menu.

You are logged-in automatically as nixos. The nixos user account has an empty password so you can use sudo without a password:

$ sudo -i

You can use loadkeys to switch to your preferred keyboard layout. (We even provide neo2 via loadkeys de neo!)

If the text is too small to be legible, try setfont ter-v32n to increase the font size.

To install over a serial port connect with 115200n8 (e.g. picocom -b 115200 /dev/ttyUSB0). When the bootloader lists boot entries, select the serial console boot entry.

# parted /dev/sda -- mklabel msdos
# parted /dev/sda -- mkpart primary 1MB -8GB
# parted /dev/sda -- mkpart primary linux-swap -8GB 100%

# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart root ext4 512MB -8GB
# parted /dev/sda -- mkpart swap linux-swap -8GB 100%
# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
# parted /dev/sda -- set 3 esp on

# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
# mkfs.fat -F 32 -n boot /dev/sda3        # (for UEFI systems only)
# mount /dev/disk/by-label/nixos /mnt
# mkdir -p /mnt/boot                      # (for UEFI systems only)
# mount -o umask=077 /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot

{ config, pkgs, ... }: {
  imports = [
    # Include the results of the hardware scan.
    ./hardware-configuration.nix
  ];

  boot.loader.grub.device = "/dev/sda";   # (for BIOS systems only)
  boot.loader.systemd-boot.enable = true; # (for UEFI systems only)

  # Note: setting fileSystems is generally not
  # necessary, since nixos-generate-config figures them out
  # automatically in hardware-configuration.nix.
  #fileSystems."/".device = "/dev/disk/by-label/nixos";

  # Enable the OpenSSH server.
  services.sshd.enable = true;
}

You can keep a NixOS system up-to-date automatically by adding the following to configuration.nix:

{
  system.autoUpgrade.enable = true;
  system.autoUpgrade.allowReboot = true;
}

This enables a periodically executed systemd service named nixos-upgrade.service. If the allowReboot option is false, it runs nixos-rebuild switch --upgrade to upgrade NixOS to the latest version in the current channel. (To see when the service runs, see systemctl list-timers.) If allowReboot is true, then the system will automatically reboot if the new generation contains a different kernel, initrd or kernel modules. You can also specify a channel explicitly, e.g.

{ system.autoUpgrade.channel = "https://channels.nixos.org/nixos-25.11"; }

To build an ISO image for the channel nixos-unstable:

$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ git switch nixos-unstable
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix

To check the content of an ISO image, mount it like so:

# mount -o loop -t iso9660 ./result/iso/nixos-image-25.05pre-git-x86_64-linux.iso /mnt/iso

If you need additional (non-distributable) drivers or firmware in the installer, you might want to extend these configurations.

For example, to build the GNOME graphical installer ISO, but with support for certain WiFi adapters present in some MacBooks, you can create the following file at modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix:

{ config, ... }:

{
  imports = [ ./installation-cd-graphical-gnome.nix ];

  boot.initrd.kernelModules = [ "wl" ];

  boot.kernelModules = [
    "kvm-intel"
    "wl"
  ];
  boot.extraModulePackages = [ config.boot.kernelPackages.broadcom_sta ];
}

Then build it like in the example above:

$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ export NIXPKGS_ALLOW_UNFREE=1
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix default.nix

The config value enforcement is implemented via mkImageMediaOverride = mkOverride 60; and therefore primes over simple value assignments, but also yields to mkForce.

This property allows image designers to implement in semantically correct ways those configuration values upon which the correct functioning of the image depends.

For example, the iso base image overrides those file systems which it needs at a minimum for correct functioning, while the installer base image overrides the entire file system layout because there can’t be any other guarantees on a live medium than those given by the live medium itself. The latter is especially true before formatting the target block device(s). On the other hand, the netboot iso only overrides its minimum dependencies since netboot images are always made-to-target.

If you want to rewrite Nix store paths, e.g., to remove the /nix/store prefix or to nest it below a parent path, you can do that through the nixStorePrefix option.

{
  fileSystems."/nix/store".device = "/dev/disk/by-partlabel/nix-store";

  image.repart.partitions = {
    "store" = {
      storePaths = [ config.system.build.toplevel ];
      nixStorePrefix = "/";
      repartConfig = {
        Type = "linux-generic";
        Label = "nix-store";
        # ...
      };
    };
  };
}

{
  fileSystems."/" = {
    device = "/dev/disk/by-partlabel/root";
    fsType = "btrfs";
    options = [ "subvol=/@" ];
  };

  fileSystems."/nix/store" = {
    device = "/dev/disk/by-partlabel/root";
    fsType = "btrfs";
    options = [ "subvol=/@nix-store" ];
  };

  image.repart.partitions = {
    "root" = {
      storePaths = [ config.system.build.toplevel ];
      nixStorePrefix = "/@nix-store";
      repartConfig = {
        Type = "root";
        Label = "root";
        Format = "btrfs";
        Subvolumes = "/@ /@nix-store";
        MakeDirectories = "/@ /@nix-store";
        # ...
      };
    };
  };
}

The image/repart.nix module can also be used to build self-contained software appliances.

The generation based update mechanism of NixOS is not suited for appliances. Updates of appliances are usually either performed by replacing the entire image with a new one or by updating partitions via an A/B scheme. See the Chrome OS update process for an example of how to achieve this. The appliance image built in the following example does not contain a configuration.nix and thus you will not be able to call nixos-rebuild from this system. Furthermore, it uses a Unified Kernel Image.

let
  pkgs = import <nixpkgs> { };
  efiArch = pkgs.stdenv.hostPlatform.efiArch;
in
(pkgs.nixos [
  (
    {
      config,
      lib,
      pkgs,
      modulesPath,
      ...
    }:
    {

      imports = [ "${modulesPath}/image/repart.nix" ];

      boot.loader.grub.enable = false;

      fileSystems."/".device = "/dev/disk/by-label/nixos";

      image.repart = {
        name = "image";
        partitions = {
          "esp" = {
            contents = {
              "/EFI/BOOT/BOOT${lib.toUpper efiArch}.EFI".source =
                "${pkgs.systemd}/lib/systemd/boot/efi/systemd-boot${efiArch}.efi";

              "/EFI/Linux/${config.system.boot.loader.ukiFile}".source =
                "${config.system.build.uki}/${config.system.boot.loader.ukiFile}";
            };
            repartConfig = {
              Type = "esp";
              Format = "vfat";
              SizeMinBytes = "96M";
            };
          };
          "root" = {
            storePaths = [ config.system.build.toplevel ];
            repartConfig = {
              Type = "root";
              Format = "ext4";
              Label = "nixos";
              Minimize = "guess";
            };
          };
        };
      };

    }
  )
]).image

The NixOS configuration file generally looks like this:

{ config, pkgs, ... }:

{
  # option definitions
}

The first line ({ config, pkgs, ... }:) denotes that this is actually a function that takes at least the two arguments config and pkgs. (These are explained later, in chapter Writing NixOS Modules) The function returns a set of option definitions ({ ... }). These definitions have the form name = value, where name is the name of an option and value is its value. For example,

{ config, pkgs, ... }:

{
  services.httpd.enable = true;
  services.httpd.adminAddr = "[email protected]";
  services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
}

defines a configuration with three option definitions that together enable the Apache HTTP Server with /webroot as the document root.

Sets can be nested, and in fact dots in option names are shorthand for defining a set containing another set. For instance, services.httpd.enable defines a set named services that contains a set named httpd, which in turn contains an option definition named enable with value true. This means that the example above can also be written as:

{ config, pkgs, ... }:

{
  services = {
    httpd = {
      enable = true;
      adminAddr = "[email protected]";
      virtualHosts = {
        localhost = {
          documentRoot = "/webroot";
        };
      };
    };
  };
}

which may be more convenient if you have lots of option definitions that share the same prefix (such as services.httpd).

NixOS checks your option definitions for correctness. For instance, if you try to define an option that doesn’t exist (that is, doesn’t have a corresponding option declaration), nixos-rebuild will give an error like:

The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.

Likewise, values in option definitions must have a correct type. For instance, services.httpd.enable must be a Boolean (true or false). Trying to give it a value of another type, such as a string, will cause an error:

The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.

Options have various types of values. The most important are:

If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration:

{
  services.httpd.virtualHosts = {
    "blog.example.org" = {
      documentRoot = "/webroot/blog.example.org";
      adminAddr = "[email protected]";
      forceSSL = true;
      enableACME = true;
    };
    "wiki.example.org" = {
      documentRoot = "/webroot/wiki.example.org";
      adminAddr = "[email protected]";
      forceSSL = true;
      enableACME = true;
    };
  };
}

It defines two virtual hosts with nearly identical configuration; the only difference is the document root directories. To prevent this duplication, we can use a let:

let
  commonConfig = {
    adminAddr = "[email protected]";
    forceSSL = true;
    enableACME = true;
  };
in
{
  services.httpd.virtualHosts = {
    "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; });
    "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.org"; });
  };
}

The let commonConfig = ... defines a variable named commonConfig. The // operator merges two attribute sets, so the configuration of the second virtual host is the set commonConfig extended with the document root option.

You can write a let wherever an expression is allowed. Thus, you also could have written:

{
  services.httpd.virtualHosts =
    let
      commonConfig = {
        # ...
      };
    in
    {
      "blog.example.org" = (
        commonConfig
        // {
          # ...
        }
      );
      "wiki.example.org" = (
        commonConfig
        // {
          # ...
        }
      );
    };
}

but not { let commonConfig = ...; in ...; } since attributes (as opposed to attribute values) are not expressions.

Functions provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the document root. This can be done as follows:

{
  services.httpd.virtualHosts =
    let
      makeVirtualHost = webroot: {
        documentRoot = webroot;
        adminAddr = "[email protected]";
        forceSSL = true;
        enableACME = true;
      };
    in
    {
      "example.org" = (makeVirtualHost "/webroot/example.org");
      "example.com" = (makeVirtualHost "/webroot/example.com");
      "example.gov" = (makeVirtualHost "/webroot/example.gov");
      "example.nl" = (makeVirtualHost "/webroot/example.nl");
    };
}

Here, makeVirtualHost is a function that takes a single argument webroot and returns the configuration for a virtual host. That function is then called for several names to produce the list of virtual host configurations.

The NixOS configuration mechanism is modular. If your configuration.nix becomes too big, you can split it into multiple files. Likewise, if you have multiple NixOS configurations (e.g. for different computers) with some commonality, you can move the common configuration into a shared file.

Modules have exactly the same syntax as configuration.nix. In fact, configuration.nix is itself a module. You can use other modules by including them from configuration.nix, e.g.:

{ config, pkgs, ... }:

{
  imports = [
    ./vpn.nix
    ./kde.nix
  ];
  services.httpd.enable = true;
  environment.systemPackages = [ pkgs.emacs ];
  # ...
}

Here, we include two modules from the same directory, vpn.nix and kde.nix. The latter might look like this:

{ config, pkgs, ... }:

{
  services.xserver.enable = true;
  services.displayManager.sddm.enable = true;
  services.desktopManager.plasma6.enable = true;
  environment.systemPackages = [ pkgs.vim ];
}

Note that both configuration.nix and kde.nix define the option environment.systemPackages. When multiple modules define an option, NixOS will try to merge the definitions. In the case of environment.systemPackages the lists of packages will be concatenated. The value in configuration.nix is merged last, so for list-type options, it will appear at the end of the merged list. If you want it to appear first, you can use mkBefore:

{ boot.kernelModules = mkBefore [ "kvm-intel" ]; }

This causes the kvm-intel kernel module to be loaded before any other kernel modules.

For other types of options, a merge may not be possible. For instance, if two modules define services.httpd.adminAddr, nixos-rebuild will give an error:

The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.

When that happens, it’s possible to force one definition take precedence over the others:

{ services.httpd.adminAddr = pkgs.lib.mkForce "[email protected]"; }

When using multiple modules, you may need to access configuration values defined in other modules. This is what the config function argument is for: it contains the complete, merged system configuration. That is, config is the result of combining the configurations returned by every module. (If you’re wondering how it’s possible that the (indirect) result of a function is passed as an input to that same function: that’s because Nix is a “lazy” language — it only computes values when they are needed. This works as long as no individual configuration value depends on itself.)

For example, here is a module that adds some packages to environment.systemPackages only if services.xserver.enable is set to true somewhere else:

{ config, pkgs, ... }:

{
  environment.systemPackages =
    if config.services.xserver.enable then
      [
        pkgs.firefox
        pkgs.thunderbird
      ]
    else
      [ ];
}

With multiple modules, it may not be obvious what the final value of a configuration option is. The command nixos-option allows you to find out:

$ nixos-option services.xserver.enable
true

$ nixos-option boot.kernelModules
[ "tun" "ipv6" "loop" ... ]

Interactive exploration of the configuration is possible using nix repl, a read-eval-print loop for Nix expressions. A typical use:

$ nix repl '<nixpkgs/nixos>'

nix-repl> config.networking.hostName
"mandark"

nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts
[ "example.org" "example.gov" ]

While abstracting your configuration, you may find it useful to generate modules using code, instead of writing files. The example below would have the same effect as importing a file which sets those options.

{ config, pkgs, ... }:

let
  netConfig = hostName: {
    networking.hostName = hostName;
    networking.useDHCP = false;
  };

in
{
  imports = [ (netConfig "nixos.localdomain") ];
}

With declarative package management, you specify which packages you want on your system by setting the option environment.systemPackages. For instance, adding the following line to configuration.nix enables the Mozilla Thunderbird email application:

{ environment.systemPackages = [ pkgs.thunderbird ]; }

The effect of this specification is that the Thunderbird package from Nixpkgs will be built or downloaded as part of the system when you run nixos-rebuild switch.

You can get a list of the available packages as follows:

$ nix-env -qaP '*' --description
nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
...

The first column in the output is the attribute name, such as nixos.thunderbird.

Note: the nixos prefix tells us that we want to get the package from the nixos channel and works only in CLI tools. In declarative configuration, use pkgs prefix (variable).

To “uninstall” a package, remove it from environment.systemPackages and run nixos-rebuild switch.

{
  nixpkgs.config = {
    allowUnfree = true;
  };
}

{
  environment.systemPackages = with pkgs; [
    sl
    (pass.withExtensions (
      subpkgs: with subpkgs; [
        pass-audit
        pass-otp
        pass-genphrase
      ]
    ))
    (python3.withPackages (subpkgs: with subpkgs; [ requests ]))
    cowsay
  ];
}

{ environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; }

{
  environment.systemPackages = [
    (pkgs.emacs.overrideAttrs (oldAttrs: {
      name = "emacs-25.0-pre";
      src = /path/to/my/emacs/tree;
    }))
  ];
}

{
  nixpkgs.config.packageOverrides = pkgs: {
    emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
  };
}

$ git clone https://github.com/NixOS/nixpkgs
$ cd nixpkgs

{ environment.systemPackages = [ pkgs.my-package ]; }

# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs

{
  environment.systemPackages =
    let
      my-hello =
        with pkgs;
        stdenv.mkDerivation rec {
          name = "hello-2.8";
          src = fetchurl {
            url = "mirror://gnu/hello/${name}.tar.gz";
            hash = "sha256-5rd/gffPfa761Kn1tl3myunD8TuM+66oy1O7XqVGDXM=";
          };
        };
    in
    [ my-hello ];
}

{ environment.systemPackages = [ (import ./my-hello.nix) ]; }

with import <nixpkgs> { }; # bring all of Nixpkgs into scope

stdenv.mkDerivation rec {
  name = "hello-2.8";
  src = fetchurl {
    url = "mirror://gnu/hello/${name}.tar.gz";
    hash = "sha256-5rd/gffPfa761Kn1tl3myunD8TuM+66oy1O7XqVGDXM=";
  };
}

$ nix-build my-hello.nix
$ ./result/bin/hello
Hello, world!

{
  programs.appimage.enable = true;
  programs.appimage.binfmt = true;
}

{
  programs.appimage.package = pkgs.appimage-run.override {
    extraPkgs = pkgs: [
      # missing libraries here, e.g.: `pkgs.libepoxy`
    ];
  };
}

With the command nix-env, you can install and uninstall packages from the command line. For instance, to install Mozilla Thunderbird:

$ nix-env -iA nixos.thunderbird

If you invoke this as root, the package is installed in the Nix profile /nix/var/nix/profiles/default and visible to all users of the system; otherwise, the package ends up in /nix/var/nix/profiles/per-user/username/profile and is not visible to other users. The -A flag specifies the package by its attribute name; without it, the package is installed by matching against its package name (e.g. thunderbird). The latter is slower because it requires matching against all available Nix packages, and is ambiguous if there are multiple matching packages.

Packages come from the NixOS channel. You typically upgrade a package by updating to the latest version of the NixOS channel:

$ nix-channel --update nixos

and then running nix-env -i again. Other packages in the profile are not affected; this is the crucial difference with the declarative style of package management, where running nixos-rebuild switch causes all packages to be updated to their current versions in the NixOS channel. You can however upgrade all packages for which there is a newer version by doing:

$ nix-env -u '*'

A package can be uninstalled using the -e flag:

$ nix-env -e thunderbird

Finally, you can roll back an undesirable nix-env action:

$ nix-env --rollback

nix-env has many more flags. For details, see the nix-env(1) manpage or the Nix manual.

Instead of using a custom perl script to create users and groups, you can use systemd-sysusers:

{ systemd.sysusers.enable = true; }

The primary benefit of this is to remove a dependency on perl.

Like systemd-sysusers, Userborn doesn’t depend on Perl but offers some more advantages over systemd-sysusers:

Userborn is the recommended way to manage users if you don’t want to rely on the Perl script. It aims to eventually replace the Perl script by default.

You can enable Userborn via:

{ services.userborn.enable = true; }

You can configure Userborn to store the password files (/etc/{group,passwd,shadow}) outside of /etc and symlink them from this location to /etc:

{ services.userborn.passwordFilesLocation = "/persistent/etc"; }

This is useful when you store /etc on a tmpfs or if /etc is immutable (e.g. when using system.etc.overlay.mutable = false;). In the latter case the original files are by default stored in /var/lib/nixos.

Userborn implements immutable users by re-mounting the password files read-only. This means that unlike when using the Perl script, trying to add a new user (e.g. via useradd) will fail right away.

Timekpr-nExT is a screen time managing application that helps optimizing time spent at computer for your subordinates, children or even for yourself.

You can enable it via:

{ services.timekpr.enable = true; }

This will install the timekpr package and start the timekpr service. You can then use the timekpra application to configure time limits for users.

NixOS supports file systems that are encrypted using LUKS (Linux Unified Key Setup). For example, here is how you create an encrypted Ext4 file system on the device /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d:

# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d

WARNING!
========
This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably.

Are you sure? (Type uppercase yes): YES
Enter LUKS passphrase: ***
Verify passphrase: ***

# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***

# mkfs.ext4 /dev/mapper/crypted

The LUKS volume should be automatically picked up by nixos-generate-config, but you might want to verify that your hardware-configuration.nix looks correct. To manually ensure that the system is automatically mounted at boot time as /, add the following to configuration.nix:

{
  boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
  fileSystems."/".device = "/dev/mapper/crypted";
}

Should grub be used as bootloader, and /boot is located on an encrypted partition, it is necessary to add the following grub option:

{ boot.loader.grub.enableCryptodisk = true; }

# export FIDO2_LABEL="/dev/sda2 @ $HOSTNAME"
# fido2luks credential "$FIDO2_LABEL"
f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7

# fido2luks -i add-key /dev/sda2 f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
Password:
Password (again):
Old password:
Old password (again):
Added to key to device /dev/sda2, slot: 2

{
  boot.initrd.luks.fido2Support = true;
  boot.initrd.luks.devices."/dev/sda2".fido2.credential =
    "f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7";
}

{ boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = true; }

{
  boot.initrd = {
    luks.devices.root = {
      crypttabExtraOpts = [ "fido2-device=auto" ];
      device = "/dev/sda2";
    };
    systemd.enable = true;
  };
}

# systemd-cryptenroll --fido2-device=auto /dev/sda2

# systemd-cryptenroll --recovery-key /dev/sda2

SSHFS is a FUSE filesystem that allows easy access to directories on a remote machine using the SSH File Transfer Protocol (SFTP). It means that if you have SSH access to a machine, no additional setup is needed to mount a directory.

$ sshfs [email protected]:/my-dir /mnt/my-dir

$ fusermount -u /mnt/my-dir

$ ssh-keygen -t ed25519 -P '' -f example-key
Generating public/private ed25519 key pair.
Your identification has been saved in example-key
Your public key has been saved in example-key.pub
The key fingerprint is:
SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation

{
  fileSystems."/mnt/my-dir" = {
    device = "[email protected]:/my-dir/";
    fsType = "sshfs";
    options = [
      # Filesystem options
      "allow_other" # for non-root access
      "_netdev" # this is a network fs
      "x-systemd.automount" # mount on demand

      # SSH options
      "reconnect" # handle connection drops
      "ServerAliveInterval=15" # keep connections alive
      "IdentityFile=/var/secrets/example-key"
    ];
  };
}

{
  options = [
    "[email protected]"
    "Port=22"
  ];
}

{
  options = [
    (builtins.replaceStrings [ " " ] [ "\\040" ]
      "ssh_command=${pkgs.openssh}/bin/ssh -v -L 8080:localhost:80"
    )
  ];

}

$ journalctl -u $(systemd-escape -p /mnt/my-dir/).mount
Jun 22 11:41:18 workstation mount[87790]: SSHFS version 3.7.1
Jun 22 11:41:18 workstation mount[87793]: executing <ssh> <-x> <-a> <-oClearAllForwardings=yes> <-oServerAliveInterval=15> <-oIdentityFile=/var/secrets/wrong-key> <-2> <[email protected]> <-s> <sftp>
Jun 22 11:41:19 workstation mount[87793]: [email protected]: Permission denied (publickey).
Jun 22 11:41:19 workstation mount[87790]: read: Connection reset by peer
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Mount process exited, code=exited, status=1/FAILURE
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Failed with result 'exit-code'.
Jun 22 11:41:19 workstation systemd[1]: Failed to mount /mnt/my-dir.
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Consumed 54ms CPU time, received 2.3K IP traffic, sent 2.7K IP traffic.

NixOS offers a convenient abstraction to create both read-only as well writable overlays.

{
  fileSystems = {
    "/writable-overlay" = {
      overlay = {
        lowerdir = [ writableOverlayLowerdir ];
        upperdir = "/.rw-writable-overlay/upper";
        workdir = "/.rw-writable-overlay/work";
      };
      # Mount the writable overlay in the initrd.
      neededForBoot = true;
    };
    "/readonly-overlay".overlay.lowerdir = [
      writableOverlayLowerdir
      writableOverlayLowerdir2
    ];
  };
}

If upperdir and workdir are not null, they will be created before the overlay is mounted.

To mount an overlay as read-only, you need to provide at least two lowerdirs.

The x11 login screen can be skipped entirely, automatically logging you into your window manager and desktop environment when you boot your computer.

This is especially helpful if you have disk encryption enabled. Since you already have to provide a password to decrypt your disk, entering a second password to login can be redundant.

To enable auto-login, you need to define your default window manager and desktop environment. If you wanted no desktop environment and i3 as your your window manager, you’d define:

{ services.displayManager.defaultSession = "none+i3"; }

Every display manager in NixOS supports auto-login, here is an example using lightdm for a user alice:

{
  services.xserver.displayManager.lightdm.enable = true;
  services.displayManager.autoLogin.enable = true;
  services.displayManager.autoLogin.user = "alice";
}

It is possible to avoid a display manager entirely and starting the X server manually from a virtual terminal. Add to your configuration:

{
  services.xserver.displayManager.startx = {
    enable = true;
    generateScript = true;
  };
}

then you can start the X server with the startx command.

The second option will generate a base xinitrc script that will run your window manager and set up the systemd user session. You can extend the script using the extraCommands option, for example:

{
  services.xserver.displayManager.startx = {
    generateScript = true;
    extraCommands = ''
      xrdb -load .Xresources
      xsetroot -solid '#666661'
      xsetroot -cursor_name left_ptr
    '';
  };
}

or, alternatively, you can write your own from scratch in ~/.xinitrc.

In this case, remember you’re responsible for starting the window manager, for example:

sxhkd &
bspwm &

and if you have enabled some systemd user service, you will probably want to also add these lines too:

# import required env variables from the current shell
systemctl --user import-environment DISPLAY XDG_SESSION_ID
# start all graphical user services
systemctl --user start nixos-fake-graphical-session.target
# start the user dbus daemon
dbus-daemon --session --address="unix:path=/run/user/$(id -u)/bus" &

The default and recommended driver for Intel Graphics in X.org is modesetting (included in the xorg-server package itself). This is a generic driver which uses the kernel mode setting (KMS) mechanism, it supports Glamor (2D graphics acceleration via OpenGL) and is actively maintained, it may perform worse in some cases (like in old chipsets).

There is a second driver, intel (provided by the xf86-video-intel package), specific to older Intel iGPUs from generation 2 to 9. It is not recommended by most distributions: it lacks several modern features (for example, it doesn’t support Glamor) and the package hasn’t been officially updated since 2015.

Third generation and older iGPUs (15-20+ years old) are not supported by the modesetting driver (X will crash upon startup). Thus, the intel driver is required for these chipsets. Otherwise, the results vary depending on the hardware, so you may have to try both drivers. Use the option services.xserver.videoDrivers to set one. The recommended configuration for modern systems is:

{ services.xserver.videoDrivers = [ "modesetting" ]; }

If you experience screen tearing no matter what, this configuration was reported to resolve the issue:

{
  services.xserver.videoDrivers = [ "intel" ];
  services.xserver.deviceSection = ''
    Option "DRI" "2"
    Option "TearFree" "true"
  '';
}

Note that this will likely downgrade the performance compared to modesetting or intel with DRI 3 (default).

NVIDIA provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because it’s not free software. You can enable it as follows:

{ services.xserver.videoDrivers = [ "nvidia" ]; }

If you have an older card, you may have to use one of the legacy drivers:

{
  hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_470;
  hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_390;
  hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_340;
}

You may need to reboot after enabling this driver to prevent a clash with other kernel modules.

Support for Synaptics touchpads (found in many laptops such as the Dell Latitude series) can be enabled as follows:

{ services.libinput.enable = true; }

The driver has many options (see Appendix A). For instance, the following disables tap-to-click behavior:

{ services.libinput.touchpad.tapping = false; }

Note: the use of services.xserver.synaptics is deprecated since NixOS 17.09.

GTK themes can be installed either to user profile or system-wide (via environment.systemPackages). To make Qt 5 applications look similar to GTK ones, you can use the following configuration:

{
  qt.enable = true;
  qt.platformTheme = "gtk2";
  qt.style = "gtk2";
}

It is possible to install custom XKB keyboard layouts using the option services.xserver.xkb.extraLayouts.

As a first example, we are going to create a layout based on the basic US layout, with an additional layer to type some greek symbols by pressing the right-alt key.

Create a file called us-greek with the following content (under a directory called symbols; it’s an XKB peculiarity that will help with testing):

xkb_symbols "us-greek"
{
  include "us(basic)"            // includes the base US keys
  include "level3(ralt_switch)"  // configures right alt as a third level switch

  key <LatA> { [ a, A, Greek_alpha ] };
  key <LatB> { [ b, B, Greek_beta  ] };
  key <LatG> { [ g, G, Greek_gamma ] };
  key <LatD> { [ d, D, Greek_delta ] };
  key <LatZ> { [ z, Z, Greek_zeta  ] };
};

A minimal layout specification must include the following:

{
  services.xserver.xkb.extraLayouts.us-greek = {
    description = "US layout with alt-gr greek";
    languages = [ "eng" ];
    symbolsFile = /yourpath/symbols/us-greek;
  };
}

Applying this customization requires rebuilding several packages, and a broken XKB file can lead to the X session crashing at login. Therefore, you’re strongly advised to test your layout before applying it:

$ nix-shell -p xorg.xkbcomp
$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY

You can inspect the predefined XKB files for examples:

$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"

Once the configuration is applied, and you did a logout/login cycle, the layout should be ready to use. You can try it by e.g. running setxkbmap us-greek and then type <alt>+a (it may not get applied in your terminal straight away). To change the default, the usual services.xserver.xkb.layout option can still be used.

A layout can have several other components besides xkb_symbols, for example we will define new keycodes for some multimedia key and bind these to some symbol.

Use the xev utility from pkgs.xorg.xev to find the codes of the keys of interest, then create a media-key file to hold the keycodes definitions

xkb_keycodes "media"
{
 <volUp>   = 123;
 <volDown> = 456;
}

Now use the newly define keycodes in media-sym:

xkb_symbols "media"
{
 key.type = "ONE_LEVEL";
 key <volUp>   { [ XF86AudioLowerVolume ] };
 key <volDown> { [ XF86AudioRaiseVolume ] };
}

As before, to install the layout do

{
  services.xserver.xkb.extraLayouts.media = {
    description = "Multimedia keys remapping";
    languages = [ "eng" ];
    symbolsFile = /path/to/media-key;
    keycodesFile = /path/to/media-sym;
  };
}

Unfortunately, the Xorg server does not (currently) support setting a keymap directly but relies instead on XKB rules to select the matching components (keycodes, types, …) of a layout. This means that components other than symbols won’t be loaded by default. As a workaround, you can set the keymap using setxkbmap at the start of the session with:

{
  services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";
}

If you are manually starting the X server, you should set the argument -xkbdir /etc/X11/xkb, otherwise X won’t find your layout files. For example with xinit run

$ xinit -- -xkbdir /etc/X11/xkb

To learn how to write layouts take a look at the XKB documentation . More example layouts can also be found here .

OpenCL is a general compute API. It is used by various applications such as Blender and Darktable to accelerate certain operations.

OpenCL applications load drivers through the Installable Client Driver (ICD) mechanism. In this mechanism, an ICD file specifies the path to the OpenCL driver for a particular GPU family. In NixOS, there are two ways to make ICD files visible to the ICD loader. The first is through the OCL_ICD_VENDORS environment variable. This variable can contain a directory which is scanned by the ICL loader for ICD files. For example:

$ export \
  OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocmPackages.clr.icd`/etc/OpenCL/vendors/

The second mechanism is to add the OpenCL driver package to hardware.graphics.extraPackages. This links the ICD file under /run/opengl-driver, where it will be visible to the ICD loader.

The proper installation of OpenCL drivers can be verified through the clinfo command of the clinfo package. This command will report the number of hardware devices that is found and give detailed information for each device:

$ clinfo | head -n3
Number of platforms  1
Platform Name        AMD Accelerated Parallel Processing
Platform Vendor      Advanced Micro Devices, Inc.

{ hardware.graphics.extraPackages = [ rocmPackages.clr.icd ]; }

{ hardware.graphics.extraPackages = [ intel-compute-runtime ]; }

Vulkan is a graphics and compute API for GPUs. It is used directly by games or indirectly though compatibility layers like DXVK.

By default, if hardware.graphics.enable is enabled, Mesa is installed and provides Vulkan for supported hardware.

Similar to OpenCL, Vulkan drivers are loaded through the Installable Client Driver (ICD) mechanism. ICD files for Vulkan are JSON files that specify the path to the driver library and the supported Vulkan version. All successfully loaded drivers are exposed to the application as different GPUs. In NixOS, there are two ways to make ICD files visible to Vulkan applications: an environment variable and a module option.

The way to do this is to add the Vulkan driver package to hardware.graphics.extraPackages. This links the ICD file under /run/opengl-driver, where it will be visible to the ICD loader.

The proper installation of Vulkan drivers can be verified through the vulkaninfo command of the vulkan-tools package. This command will report the hardware devices and drivers found, in this example output amdvlk and radv:

$ vulkaninfo | grep GPU
                GPU id  : 0 (Unknown AMD GPU)
                GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
     ...
GPU0:
        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
        deviceName     = Unknown AMD GPU
GPU1:
        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU

A simple graphical application that uses Vulkan is vkcube from the vulkan-tools package.

VA-API (Video Acceleration API) is an open-source library and API specification, which provides access to graphics hardware acceleration capabilities for video processing.

VA-API drivers are loaded by libva. The version in nixpkgs is built to search the opengl driver path, so drivers can be installed in hardware.graphics.extraPackages.

VA-API can be tested using:

$ nix-shell -p libva-utils --run vainfo

{ hardware.graphics.extraPackages = [ intel-media-driver ]; }

{ hardware.graphics.extraPackages = [ intel-vaapi-driver ]; }

Thunar (the Xfce file manager) is automatically enabled when Xfce is enabled. To enable Thunar without enabling Xfce, use the configuration option programs.thunar.enable instead of adding pkgs.xfce.thunar to environment.systemPackages.

If you’d like to add extra plugins to Thunar, add them to programs.thunar.plugins. You shouldn’t just add them to environment.systemPackages.

Even after enabling udisks2, volume management might not work. Thunar and/or the desktop takes time to show up. Thunar will spit out this kind of message on start (look at journalctl --user -b).

Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported

This is caused by some needed GNOME services not running. This is all fixed by enabling “Launch GNOME services on startup” in the Advanced tab of the Session and Startup settings panel. Alternatively, you can run this command to do the same thing.

$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true

It is necessary to log out and log in again for this to take effect.

To facilitate network configuration, some desktop environments use NetworkManager. You can enable NetworkManager by setting:

{ networking.networkmanager.enable = true; }

some desktop managers (e.g., GNOME) enable NetworkManager automatically for you.

All users that should have permission to change network settings must belong to the networkmanager group:

{ users.users.alice.extraGroups = [ "networkmanager" ]; }

NetworkManager is controlled using either nmcli or nmtui (curses-based terminal user interface). See their manual pages for details on their usage. Some desktop environments (GNOME, KDE) have their own configuration tools for NetworkManager. On XFCE, there is no configuration tool for NetworkManager by default: by enabling programs.nm-applet.enable, the graphical applet will be installed and will launch automatically when the graphical session is started.

{
  networking.networkmanager.unmanaged = [
    "*"
    "except:type:wwan"
    "except:type:gsm"
  ];
}

Secure shell (SSH) access to your machine can be enabled by setting:

{ services.openssh.enable = true; }

By default, root logins using a password are disallowed. They can be disabled entirely by setting services.openssh.settings.PermitRootLogin to "no".

You can declaratively specify authorised public keys for a user as follows:

{
  users.users.alice.openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
}

By default, NixOS uses DHCP (specifically, dhcpcd) to automatically configure network interfaces. However, you can configure an interface manually as follows:

{
  networking.interfaces.eth0.ipv4.addresses = [
    {
      address = "192.168.1.2";
      prefixLength = 24;
    }
  ];
}

Typically you’ll also want to set a default gateway and set of name servers:

{
  networking.defaultGateway = "192.168.1.1";
  networking.nameservers = [ "8.8.8.8" ];
}

The host name is set using networking.hostName:

{ networking.hostName = "cartman"; }

The default host name is nixos. Set it to the empty string ("") to allow the DHCP server to provide the host name.

IPv6 is enabled by default. Stateless address autoconfiguration is used to automatically assign IPv6 addresses to all interfaces, and Privacy Extensions (RFC 4941) are enabled by default. You can adjust the default for this by setting networking.tempAddresses. This option may be overridden on a per-interface basis by networking.interfaces.<name>.tempAddress. You can disable IPv6 support globally by setting:

{ networking.enableIPv6 = false; }

You can disable IPv6 on a single interface using a normal sysctl (in this example, we use interface eth0):

{ boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true; }

As with IPv4 networking interfaces are automatically configured via DHCPv6. You can configure an interface manually:

{
  networking.interfaces.eth0.ipv6.addresses = [
    {
      address = "fe00:aa:bb:cc::2";
      prefixLength = 64;
    }
  ];
}

For configuring a gateway, optionally with explicitly specified interface:

{
  networking.defaultGateway6 = {
    address = "fe00::1";
    interface = "enp0s3";
  };
}

See the section called “IPv4 Configuration” for similar examples and additional information.

NixOS has a simple stateful firewall that blocks incoming connections and other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic. It is enabled by default. It can be disabled as follows:

{ networking.firewall.enable = false; }

If the firewall is enabled, you can open specific TCP ports to the outside world:

{
  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
}

Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is enabled (services.openssh.enable = true). UDP ports can be opened through networking.firewall.allowedUDPPorts.

To open ranges of TCP ports:

{
  networking.firewall.allowedTCPPortRanges = [
    {
      from = 4000;
      to = 4007;
    }
    {
      from = 8000;
      to = 8010;
    }
  ];
}

Similarly, UDP port ranges can be opened through networking.firewall.allowedUDPPortRanges.

For a desktop installation using NetworkManager (e.g., GNOME), you just have to make sure the user is in the networkmanager group and you can skip the rest of this section on wireless networks.

NixOS will start wpa_supplicant for you if you enable this setting:

{ networking.wireless.enable = true; }

NixOS lets you specify networks for wpa_supplicant declaratively:

{
  networking.wireless.networks = {
    # SSID with no spaces or special characters
    echelon = {
      psk = "abcdefgh";
    };
    # SSID with spaces and/or special characters
    "echelon's AP" = {
      psk = "ijklmnop";
    };
    # Hidden SSID
    echelon = {
      hidden = true;
      psk = "qrstuvwx";
    };
    free.wifi = { }; # Public wireless network
  };
}

Be aware that keys will be written to the nix store in plaintext! When no networks are set, it will default to using a configuration file at /etc/wpa_supplicant.conf. You should edit this file yourself to define wireless networks, WPA keys and so on (see wpa_supplicant.conf(5)).

If you are using WPA2 you can generate pskRaw key using wpa_passphrase:

$ wpa_passphrase ESSID PSK
network={
        ssid="echelon"
        #psk="abcdefgh"
        psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
}

{
  networking.wireless.networks = {
    echelon = {
      pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
    };
  };
}

or you can use it to directly generate the wpa_supplicant.conf:

# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf

After you have edited the wpa_supplicant.conf, you need to restart the wpa_supplicant service.

# systemctl restart wpa_supplicant.service

You can use networking.localCommands to specify shell commands to be run at the end of network-setup.service. This is useful for doing network configuration not covered by the existing NixOS modules. For instance, to statically configure an IPv6 address:

{
  networking.localCommands = ''
    ip -6 addr add 2001:610:685:1::1/64 dev eth0
  '';
}

NixOS uses the udev predictable naming scheme to assign names to network interfaces. This means that by default cards are not given the traditional names like eth0 or eth1, whose order can change unpredictably across reboots. Instead, relying on physical locations and firmware information, the scheme produces names like ens1, enp2s0, etc.

These names are predictable but less memorable and not necessarily stable: for example installing new hardware or changing firmware settings can result in a name change. If this is undesirable, for example if you have a single ethernet card, you can revert to the traditional scheme by setting networking.usePredictableInterfaceNames to false.

{
  systemd.network.links."10-wan" = {
    matchConfig.PermanentMACAddress = "52:54:00:12:01:01";
    linkConfig.Name = "wan";
  };
}

{
  boot.initrd.services.udev.rules = ''
    SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
    ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
  '';
}

Please refer to the Nixpkgs manual for the various ways of building a custom kernel.

To use your custom kernel package in your NixOS configuration, set

{ boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel; }

The Linux kernel does not have Rust language support enabled by default. For kernel versions 6.7 or newer, experimental Rust support can be enabled. In a NixOS configuration, set:

{
  boot.kernelPatches = [
    {
      name = "Rust Support";
      patch = null;
      features = {
        rust = true;
      };
    }
  ];
}

This section was moved to the Nixpkgs manual.

It’s a common issue that the latest stable version of ZFS doesn’t support the latest available Linux kernel. It is recommended to use the latest available LTS that’s compatible with ZFS. Usually this is the default kernel provided by nixpkgs (i.e. pkgs.linuxPackages).

This section focuses on configuring a web-based server on top of the Apache HTTP server, which uses WebDAV/DeltaV for communication.

For more information on the general setup, please refer to the the appropriate section of the Subversion book.

To configure, include in /etc/nixos/configuration.nix code to activate Apache HTTP, setting services.httpd.adminAddr appropriately:

{
  services.httpd.enable = true;
  services.httpd.adminAddr = "...";
  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
}

For a simple Subversion server with basic authentication, configure the Subversion module for Apache as follows, setting hostName and documentRoot appropriately, and SVNParentPath to the parent directory of the repositories, AuthzSVNAccessFile to the location of the .authz file describing access permission, and AuthUserFile to the password file.

{
  services.httpd.extraModules = [
    # note that order is *super* important here
    {
      name = "dav_svn";
      path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so";
    }
    {
      name = "authz_svn";
      path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so";
    }
  ];
  services.httpd.virtualHosts = {
    "svn" = {
      hostName = HOSTNAME;
      documentRoot = DOCUMENTROOT;
      locations."/svn".extraConfig = ''
        DAV svn
        SVNParentPath REPO_PARENT
        AuthzSVNAccessFile ACCESS_FILE
        AuthName "SVN Repositories"
        AuthType Basic
        AuthUserFile PASSWORD_FILE
        Require valid-user
      '';
    };
  };
}

The key "svn" is just a symbolic name identifying the virtual host. The "/svn" in locations."/svn".extraConfig is the path underneath which the repositories will be served.

This page explains how to set up the Subversion configuration itself. This boils down to the following:

Underneath REPO_PARENT repositories can be set up as follows:

$ svn create REPO_NAME

Repository files need to be accessible by wwwrun:

$ chown -R wwwrun:wwwrun REPO_PARENT

The password file PASSWORD_FILE can be created as follows:

$ htpasswd -cs PASSWORD_FILE USER_NAME

Additional users can be set up similarly, omitting the c flag:

$ htpasswd -s PASSWORD_FILE USER_NAME

The file describing access permissions ACCESS_FILE will look something like the following:

[/]
* = r

[REPO_NAME:/]
USER_NAME = rw

The Subversion repositories will be accessible as http://HOSTNAME/svn/REPO_NAME.

All of the core apps, optional apps, games, and core developer tools from GNOME are available.

To enable the GNOME desktop use:

{
  services.desktopManager.gnome.enable = true;
  services.displayManager.gdm.enable = true;
}

The default applications used in NixOS are very minimal, inspired by the defaults used in gnome-build-meta.

{ services.gnome.core-apps.enable = false; }

{
  services.gnome.localsearch.enable = false;
  services.gnome.tinysparql.enable = false;
}

{ services.gnome.games.enable = true; }

{ services.gnome.core-developer-tools.enable = true; }

GNOME Flashback provides a desktop environment based on the classic GNOME 2 architecture. You can enable the default GNOME Flashback session, which uses the Metacity window manager, with:

{ services.desktopManager.gnome.flashback.enableMetacity = true; }

It is also possible to create custom sessions that replace Metacity with a different window manager using services.desktopManager.gnome.flashback.customSessions.

The following example uses xmonad window manager:

{
  services.desktopManager.gnome.flashback.customSessions = [
    {
      wmName = "xmonad";
      wmLabel = "XMonad";
      wmCommand = "${pkgs.haskellPackages.xmonad}/bin/xmonad";
      enableGnomePanel = false;
    }
  ];
}

Icon themes and GTK themes don’t require any special option to install in NixOS.

You can add them to environment.systemPackages and switch to them with GNOME Tweaks. If you’d like to do this manually in dconf, change the values of the following keys:

/org/gnome/desktop/interface/gtk-theme
/org/gnome/desktop/interface/icon-theme

in dconf-editor

Most Shell extensions are packaged under the gnomeExtensions attribute. Some packages that include Shell extensions, like gpaste, don’t have their extension decoupled under this attribute.

You can install them like any other package:

{
  environment.systemPackages = [
    pkgs.gnomeExtensions.dash-to-dock
    pkgs.gnomeExtensions.gsconnect
    pkgs.gnomeExtensions.mpris-indicator-button
  ];
}

Unfortunately, we lack a way for these to be managed in a completely declarative way. So you have to enable them manually with an Extensions application. It is possible to use a GSettings override for this on org.gnome.shell.enabled-extensions, but that will only influence the default value.

Majority of software building on the GNOME platform use GLib’s GSettings system to manage runtime configuration. For our purposes, the system consists of XML schemas describing the individual configuration options, stored in the package, and a settings backend, where the values of the settings are stored. On NixOS, like on most Linux distributions, dconf database is used as the backend.

GSettings vendor overrides can be used to adjust the default values for settings of the GNOME desktop and apps by replacing the default values specified in the XML schemas. Using overrides will allow you to pre-seed user settings before you even start the session.

You can override the default GSettings values using the services.desktopManager.gnome.extraGSettingsOverrides option.

Take note that whatever packages you want to override GSettings for, you need to add them to services.desktopManager.gnome.extraGSettingsOverridePackages.

You can use dconf-editor tool to explore which GSettings you can set.

{
  services.desktopManager.gnome = {
    extraGSettingsOverrides = ''
      # Change default background
      [org.gnome.desktop.background]
      picture-uri='file://${pkgs.nixos-artwork.wallpapers.mosaic-blue.gnomeFilePath}'

      # Favorite apps in gnome-shell
      [org.gnome.shell]
      favorite-apps=['org.gnome.Console.desktop', 'org.gnome.Nautilus.desktop']
    '';

    extraGSettingsOverridePackages = [
      pkgs.gsettings-desktop-schemas # for org.gnome.desktop
      pkgs.gnome-shell # for org.gnome.shell
    ];
  };
}

All of Pantheon is working in NixOS and the applications should be available, aside from a few exceptions. To enable Pantheon, set

{ services.desktopManager.pantheon.enable = true; }

This automatically enables LightDM and Pantheon’s LightDM greeter. If you’d like to disable this, set

{
  services.xserver.displayManager.lightdm.greeters.pantheon.enable = false;
  services.xserver.displayManager.lightdm.enable = false;
}

but please be aware using Pantheon without LightDM as a display manager will break screenlocking from the UI. The NixOS module for Pantheon installs all of Pantheon’s default applications. If you’d like to not install Pantheon’s apps, set

{ services.pantheon.apps.enable = false; }

You can also use environment.pantheon.excludePackages to remove any other app (like elementary-mail).

Wingpanel and Switchboard work differently than they do in other distributions, as far as using plugins. You cannot install a plugin globally (like with environment.systemPackages) to start using it. You should instead be using the following options:

to configure the programs with plugs or indicators.

The difference in NixOS is both these programs are patched to load plugins from a directory that is the value of an environment variable. All of which is controlled in Nix. If you need to configure the particular packages manually you can override the packages like:

wingpanel-with-indicators.override {
  indicators = [ pkgs.some-special-indicator ];
}

switchboard-with-plugs.override { plugs = [ pkgs.some-special-plug ]; }

please note that, like how the NixOS options describe these as extra plugins, this would only add to the default plugins included with the programs. If for some reason you’d like to configure which plugins to use exactly, both packages have an argument for this:

wingpanel-with-indicators.override {
  useDefaultIndicators = false;
  indicators = specialListOfIndicators;
}

switchboard-with-plugs.override {
  useDefaultPlugs = false;
  plugs = specialListOfPlugs;
}

this could be most useful for testing a particular plug-in in isolation.

Bootloaders should use RFC-0125’s Bootspec format and synthesis tools to identify the key properties for bootable system generations.

The first step is to embed your secret in a JWE file. JWE files have to be created through the clevis command line. 3 types of policies are supported:

Secrets are pinned against the presence of a TPM2 device, for example:

echo -n hi | clevis encrypt tpm2 '{}' > hi.jwe

Secrets are pinned against the presence of a Tang server, for example:

echo -n hi | clevis encrypt tang '{"url": "http://tang.local"}' > hi.jwe

Using Shamir’s Secret Sharing (sss), secrets are pinned using a combination of the two preceding policies. For example:

echo -n hi | clevis encrypt sss \
'{"t": 2, "pins": {"tpm2": {"pcr_ids": "0"}, "tang": {"url": "http://tang.local"}}}' \
> hi.jwe

For more complete documentation on how to generate a secret with clevis, see the clevis documentation.

In order to activate unattended decryption of a resource at boot, enable the clevis module:

{ boot.initrd.clevis.enable = true; }

Then, specify the device you want to decrypt using a given clevis secret. Clevis will automatically try to decrypt the device at boot and will fallback to interactive unlocking if the decryption policy is not fulfilled.

{ boot.initrd.clevis.devices."/dev/nvme0n1p1".secretFile = ./nvme0n1p1.jwe; }

Only bcachefs, zfs and luks encrypted devices are supported at this time.

Garage provides a cookbook documentation on how to upgrade: https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/

Here are some baseline instructions to handle advanced upgrades in Garage, when in doubt, please refer to upstream instructions.

Your upgraded cluster should be in a working state, re-enable API and web access.

As stated in the previous paragraph, we must provide a clean upgrade-path for Garage since it cannot move more than one major version forward on a single upgrade. This chapter adds some notes how Garage updates should be rolled out in the future. This is inspired from how Nextcloud does it.

While patch-level updates are no problem and can be done directly in the package-expression (and should be backported to supported stable branches after that), major-releases should be added in a new attribute (e.g. Garage v3.0.0 should be available in nixpkgs as pkgs.garage_3). To provide simple upgrade paths it’s generally useful to backport those as well to stable branches. As long as the package-default isn’t altered, this won’t break existing setups. After that, the versioning-warning in the garage-module should be updated to make sure that the package-option selects the latest version on fresh setups.

If major-releases will be abandoned by upstream, we should check first if those are needed in NixOS for a safe upgrade-path before removing those. In that case we should keep those packages, but mark them as insecure in an expression like this (in <nixpkgs/pkgs/tools/filesystem/garage/default.nix>):

# ...
{
  garage_1_2_0 = generic {
    version = "1.2.0";
    sha256 = "0000000000000000000000000000000000000000000000000000";
    eol = true;
  };
}

Ideally we should make sure that it’s possible to jump two NixOS versions forward: i.e. the warnings and the logic in the module should guard a user to upgrade from a Garage on e.g. 22.11 to a Garage on 23.11.

YouTrack exposes a web GUI installer on first login. You need a token to access it. You can find this token in the log of the youtrack service. The log line looks like

* JetBrains YouTrack 2023.3 Configuration Wizard will be available on [http://127.0.0.1:8090/?wizard_token=somelongtoken] after start

Starting with YouTrack 2023.1, JetBrains no longer distributes it as as JAR. The new distribution with the JetBrains Launcher as a ZIP changed the basic data structure and also some configuration parameters. Check out https://www.jetbrains.com/help/youtrack/server/YouTrack-Java-Start-Parameters.html for more information on the new configuration options. When upgrading to YouTrack 2023.1 or higher, a migration script will move the old state directory to /var/lib/youtrack/2022_3 as a backup. A one-time manual update is required:

If you migrate a larger YouTrack instance, it might be useful to set -Dexodus.entityStore.refactoring.forceAll=true in services.youtrack.generalParameters for the first startup of YouTrack 2023.x.

By default the module will execute Szurubooru server only, the web client only contains static files that can be reached via a reverse proxy.

Here is a basic configuration:

{
  services.szurubooru = {
    enable = true;

    server = {
      port = 8080;

      settings = {
        domain = "https://szurubooru.domain.tld";
        secretFile = /path/to/secret/file;
      };
    };

    database = {
      passwordFile = /path/to/secret/file;
    };
  };
}

The preferred method to run this service is behind a reverse proxy not to expose an open port. For example, here is a minimal Nginx configuration:

{
  services.szurubooru = {
    enable = true;

    server = {
      port = 8080;
      # ...
    };

    # ...
  };

  services.nginx.virtualHosts."szurubooru.domain.tld" = {
    locations = {
      "/api/".proxyPass = "http://localhost:8080/";
      "/data/".root = config.services.szurubooru.dataDir;
      "/" = {
        root = config.services.szurubooru.client.package;
        tryFiles = "$uri /index.htm";
      };
    };
  };
}

Not all configuration options of the server are available directly in this module, but you can add them in services.szurubooru.server.settings:

{
  services.szurubooru = {
    enable = true;

    server.settings = {
      domain = "https://szurubooru.domain.tld";
      delete_source_files = "yes";
      contact_email = "[email protected]";
    };
  };
}

You can find all of the options in the default config file available here.

By default, the module will execute Suwayomi-Server backend and web UI:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;
  };
}

It runs in the systemd service named suwayomi-server in the data directory /var/lib/suwayomi-server.

You can change the default parameters with some other parameters:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;

    dataDir = "/var/lib/suwayomi"; # Default is "/var/lib/suwayomi-server"
    openFirewall = true;

    settings = {
      server.port = 4567;
    };
  };
}

If you want to create a desktop icon, you can activate the system tray option:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;

    dataDir = "/var/lib/suwayomi"; # Default is "/var/lib/suwayomi-server"
    openFirewall = true;

    settings = {
      server.port = 4567;
      server.enableSystemTray = true;
    };
  };
}

You can configure a basic authentication to the web interface with:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;

    openFirewall = true;

    settings = {
      server.port = 4567;
      server = {
        basicAuthEnabled = true;
        basicAuthUsername = "username";

        # NOTE: this is not a real upstream option
        basicAuthPasswordFile = ./path/to/the/password/file;
      };
    };
  };
}

Not all the configuration options are available directly in this module, but you can add the other options of suwayomi-server with:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;

    openFirewall = true;

    settings = {
      server = {
        port = 4567;
        autoDownloadNewChapters = false;
        maxSourcesInParallel = 6;
        extensionRepos = [
          "https://raw.githubusercontent.com/MY_ACCOUNT/MY_REPO/repo/index.min.json"
        ];
      };
    };
  };
}

By default, the module will execute strfry:

{ ... }:

{
  services.strfry.enable = true;
}

It runs in the systemd service named strfry.

You can configure nginx as a reverse proxy with:

{ ... }:

{
  security.acme = {
    acceptTerms = true;
    defaults.email = "[email protected]";
  };

  services.nginx.enable = true;
  services.nginx.virtualHosts."strfry.example.com" = {
    addSSL = true;
    enableACME = true;
    locations."/" = {
      proxyPass = "http://127.0.0.1:${toString config.services.strfry.settings.relay.port}";
      proxyWebsockets = true; # nostr uses websockets
    };
  };

  services.strfry.enable = true;
}

At first, a secret key is needed to be generated. This can be done with e.g.

$ openssl rand -base64 64

After that, plausible can be deployed like this:

{
  services.plausible = {
    enable = true;
    server = {
      baseUrl = "http://analytics.example.org";
      # secretKeybaseFile is a path to the file which contains the secret generated
      # with openssl as described above.
      secretKeybaseFile = "/run/secrets/plausible-secret-key-base";
    };
  };
}

By default, the module will execute Pingvin Share backend and frontend on the ports 8080 and 3000.

I will run two systemd services named pingvin-share-backend and pingvin-share-frontend in the specified data directory.

Here is a basic configuration:

{
  services-pingvin-share = {
    enable = true;

    openFirewall = true;

    backend.port = 9010;
    frontend.port = 9011;
  };
}

The preferred method to run this service is behind a reverse proxy not to expose an open port. This, you can configure Nginx such like this:

{
  services-pingvin-share = {
    enable = true;

    hostname = "pingvin-share.domain.tld";
    https = true;

    nginx.enable = true;
  };
}

Furthermore, you can increase the maximal size of an uploaded file with the option services.nginx.clientMaxBodySize.

Example configuration:

{
  services.pihole-web = {
    enable = true;
    ports = [ 80 ];
  };
}

The dashboard can be configured using services.pihole-ftl.settings, in particular the webserver subsection.

the minimum to start pict-rs is

{ services.pict-rs.enable = true; }

this will start the http server on port 8080 by default.

pict-rs offers the following endpoints:

OpenCloud is configured using a combination of YAML and environment variables. The full documentation can be found at OpenCloud Admin Docs.

The general flow of configuring OpenCloud is:

Please note that current NixOS module for OpenCloud is configured to run in fullstack mode, which starts all the services for OpenCloud in a single instance, in so called supervised mode. This will start multiple OpenCloud services and listen on multiple other ports.

Current known services and their ports are as below:

Nextcloud is a PHP-based application which requires an HTTP server (services.nextcloud and optionally supports services.nginx).

For the database, you can set services.nextcloud.config.dbtype to either sqlite (the default), mysql, or pgsql. The simplest is sqlite, which will be automatically created and managed by the application. For the last two, you can easily create a local database by setting services.nextcloud.database.createLocally to true, Nextcloud will automatically be configured to connect to it through socket.

A very basic configuration may look like this:

{ pkgs, ... }:
{
  services.nextcloud = {
    enable = true;
    hostName = "nextcloud.tld";
    database.createLocally = true;
    config = {
      dbtype = "pgsql";
      adminpassFile = "/path/to/admin-pass-file";
    };
  };

  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
}

The hostName option is used internally to configure an HTTP server using PHP-FPM and nginx. The config attribute set is used by the imperative installer and all values are written to an additional file to ensure that changes can be applied by changing the module’s options.

In case the application serves multiple domains (those are checked with $_SERVER['HTTP_HOST']) it’s needed to add them to services.nextcloud.settings.trusted_domains.

Auto updates for Nextcloud apps can be enabled using services.nextcloud.autoUpdateApps.

The management command occ can be invoked by using the nextcloud-occ wrapper that’s globally available on a system with Nextcloud enabled.

It requires elevated permissions to become the nextcloud user. Given the way the privilege escalation is implemented, parameters passed via the environment to Nextcloud are currently ignored, except for OC_PASS and NC_PASS.

Custom service units that need to run nextcloud-occ either need elevated privileges or the systemd configuration from nextcloud-setup.service (recommended):

{ config, ... }:
{
  systemd.services.my-custom-service = {
    script = ''
      nextcloud-occ …
    '';
    serviceConfig = {
      inherit (config.systemd.services.nextcloud-cron.serviceConfig)
        User
        LoadCredential
        KillMode
        ;
    };
  };
}

Please note that the options required are subject to change. Please make sure to read the release notes when upgrading.

By default, nginx is used as reverse-proxy for nextcloud. However, it’s possible to use e.g. httpd by explicitly disabling nginx using services.nginx.enable and fixing the settings listen.owner & listen.group in the phpfpm pool nextcloud.

Nextcloud apps are installed statefully through the web interface. Some apps may require extra PHP extensions to be installed. This can be configured with the services.nextcloud.phpExtraExtensions setting.

Alternatively, extra apps can also be declared with the services.nextcloud.extraApps setting. When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps that are managed by Nix:

{ config, pkgs, ... }:
{
  services.nextcloud.extraApps = with config.services.nextcloud.package.packages.apps; {
    inherit user_oidc calendar contacts;
  };
}

Keep in mind that this is essentially a mirror of the apps from the appstore, but managed in nixpkgs. This is by no means a curated list of apps that receive special testing on each update.

If you want automatic updates it is recommended that you use web interface to install apps.

As stated in the previous paragraph, we must provide a clean upgrade-path for Nextcloud since it cannot move more than one major version forward on a single upgrade. This chapter adds some notes how Nextcloud updates should be rolled out in the future.

While minor and patch-level updates are no problem and can be done directly in the package-expression (and should be backported to supported stable branches after that), major-releases should be added in a new attribute (e.g. Nextcloud v19.0.0 should be available in nixpkgs as pkgs.nextcloud19). To provide simple upgrade paths it’s generally useful to backport those as well to stable branches. As long as the package-default isn’t altered, this won’t break existing setups. After that, the versioning-warning in the nextcloud-module should be updated to make sure that the package-option selects the latest version on fresh setups.

If major-releases will be abandoned by upstream, we should check first if those are needed in NixOS for a safe upgrade-path before removing those. In that case we should keep those packages, but mark them as insecure in an expression like this (in <nixpkgs/pkgs/servers/nextcloud/default.nix>):

# ...
{
  nextcloud17 = generic {
    version = "17.0.x";
    sha256 = "0000000000000000000000000000000000000000000000000000";
    eol = true;
  };
}

Ideally we should make sure that it’s possible to jump two NixOS versions forward: i.e. the warnings and the logic in the module should guard a user to upgrade from a Nextcloud on e.g. 19.09 to a Nextcloud on 20.09.

You also need to configure a MariaDB or MySQL database and -user for Matomo yourself, and enter those credentials in your browser. You can use passwordless database authentication via the UNIX_SOCKET authentication plugin with the following SQL commands:

# For MariaDB
INSTALL PLUGIN unix_socket SONAME 'auth_socket';
CREATE DATABASE matomo;
CREATE USER 'matomo'@'localhost' IDENTIFIED WITH unix_socket;
GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';

# For MySQL
INSTALL PLUGIN auth_socket SONAME 'auth_socket.so';
CREATE DATABASE matomo;
CREATE USER 'matomo'@'localhost' IDENTIFIED WITH auth_socket;
GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';

Then fill in matomo as database user and database name, and leave the password field blank. This authentication works by allowing only the matomo unix user to authenticate as the matomo database user (without needing a password), but no other users. For more information on passwordless login, see https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/.

Of course, you can use password based authentication as well, e.g. when the database is not on the same host.

This module comes with the systemd service matomo-archive-processing.service and a timer that automatically triggers archive processing every hour. This means that you can safely disable browser triggers for Matomo archiving at Administration > System > General Settings.

With automatic archive processing, you can now also enable to delete old visitor logs at Administration > System > Privacy, but make sure that you run systemctl start matomo-archive-processing.service at least once without errors if you have already collected data before, so that the reports get archived before the source data gets deleted.

You only need to take backups of your MySQL database and the /var/lib/matomo/config/config.ini.php file. Use a user in the matomo group or root to access the file. For more information, see https://matomo.org/faq/how-to-install/faq_138/.

You can use other web servers by forwarding calls for index.php and piwik.php to the services.phpfpm.pools.<name>.socket fastcgi unix socket. You can use the nginx configuration in the module code as a reference to what else should be configured.

The minimum to start lemmy is

{
  services.lemmy = {
    enable = true;
    settings = {
      hostname = "lemmy.union.rocks";
      database.createLocally = true;
    };
    caddy.enable = true;
  };
}

This will start the backend on port 8536 and the frontend on port 1234. It will expose your instance with a caddy reverse proxy to the hostname you’ve provided. Postgres will be initialized on that same instance automatically.

On first connection you will be asked to define an admin user.

An administrative user with the username admin is automatically created in the master realm. Its initial password can be configured by setting services.keycloak.initialAdminPassword and defaults to changeme. The password is not stored safely and should be changed immediately in the admin panel.

Refer to the Keycloak Server Administration Guide for information on how to administer your Keycloak instance.

Keycloak can be used with either PostgreSQL, MariaDB or MySQL. Which one is used can be configured in services.keycloak.database.type. The selected database will automatically be enabled and a database and role created unless services.keycloak.database.host is changed from its default of localhost or services.keycloak.database.createLocally is set to false.

External database access can also be configured by setting services.keycloak.database.host, services.keycloak.database.name, services.keycloak.database.username, services.keycloak.database.useSSL and services.keycloak.database.caCert as appropriate. Note that you need to manually create the database and allow the configured database user full access to it.

services.keycloak.database.passwordFile must be set to the path to a file containing the password used to log in to the database. If services.keycloak.database.host and services.keycloak.database.createLocally are kept at their defaults, the database role keycloak with that password is provisioned on the local database instance.

The hostname is used to build the public URL used as base for all frontend requests and must be configured through services.keycloak.settings.hostname.

services.keycloak.settings.hostname-backchannel-dynamic Keycloak has the capability to offer a separate URL for backchannel requests, enabling internal communication while maintaining the use of a public URL for frontchannel requests. Moreover, the backchannel is dynamically resolved based on incoming headers endpoint.

For more information on hostname configuration, see the Hostname section of the Keycloak Server Installation and Configuration Guide.

By default, Keycloak won’t accept unsecured HTTP connections originating from outside its local network.

HTTPS support requires a TLS/SSL certificate and a private key, both PEM formatted. Their paths should be set through services.keycloak.sslCertificate and services.keycloak.sslCertificateKey.

You can package custom themes and make them visible to Keycloak through services.keycloak.themes. See the Themes section of the Keycloak Server Development Guide and the description of the aforementioned NixOS option for more information.

Keycloak server configuration parameters can be set in services.keycloak.settings. These correspond directly to options in conf/keycloak.conf. Some of the most important parameters are documented as suboptions, the rest can be found in the All configuration section of the Keycloak Server Installation and Configuration Guide.

Options containing secret data should be set to an attribute set containing the attribute _secret - a string pointing to a file containing the value the option should be set to. See the description of services.keycloak.settings for an example.

A basic configuration with some custom settings could look like this:

{
  services.keycloak = {
    enable = true;
    settings = {
      hostname = "keycloak.example.com";
      hostname-strict-backchannel = true;
    };
    initialAdminPassword = "e6Wcm0RrtegMEHl"; # change on first login
    sslCertificate = "/run/keys/ssl_cert";
    sslCertificateKey = "/run/keys/ssl_key";
    database.passwordFile = "/run/keys/db_password";
  };
}

A minimal configuration using Let’s Encrypt for TLS certificates looks like this:

{
  services.jitsi-meet = {
    enable = true;
    hostName = "jitsi.example.com";
  };
  services.jitsi-videobridge.openFirewall = true;
  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
  security.acme.email = "[email protected]";
  security.acme.acceptTerms = true;
}

Jitsi Meet depends on the Prosody XMPP server only for message passing from the web browser while the default Prosody configuration is intended for use with standalone XMPP clients and XMPP federation. If you only use Prosody as a backend for Jitsi Meet it is therefore recommended to also enable services.jitsi-meet.prosody.lockdown option to disable unnecessary Prosody features such as federation or the file proxy.

Here is the minimal configuration with additional configurations:

{
  services.jitsi-meet = {
    enable = true;
    hostName = "jitsi.example.com";
    prosody.lockdown = true;
    config = {
      enableWelcomePage = false;
      prejoinPageEnabled = true;
      defaultLang = "fi";
    };
    interfaceConfig = {
      SHOW_JITSI_WATERMARK = false;
      SHOW_WATERMARK_FOR_GUESTS = false;
    };
  };
  services.jitsi-videobridge.openFirewall = true;
  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
  security.acme.email = "[email protected]";
  security.acme.acceptTerms = true;
}

Immich instances that were setup before 25.11 (as in system.stateVersion = 25.11;) will be automatically migrated to VectorChord. Note that this migration is not reversible, so database dumps should be created if desired.

See Immich documentation for more details about the automatic migration.

After a successful migration, pgvecto-rs should be removed from the database installation, unless other applications depend on it.

A minimal configuration looks like this:

{
  services.honk = {
    enable = true;
    host = "0.0.0.0";
    port = 8080;
    username = "username";
    passwordFile = "/etc/honk/password.txt";
    servername = "honk.example.com";
  };

  networking.firewall.allowedTCPPorts = [ 8080 ];
}

The minimum configuration to start hatsu server would look like this:

{
  services.hatsu = {
    enable = true;
    settings = {
      HATSU_DOMAIN = "hatsu.local";
      HATSU_PRIMARY_ACCOUNT = "example.com";
    };
  };
}

this will start the hatsu server on port 3939 and save the database in /var/lib/hatsu/hatsu.sqlite3.

Please refer to the Hatsu Documentation for additional configuration options.

A very basic configuration may look like this:

{ pkgs, ... }:
{
  services.grocy = {
    enable = true;
    hostName = "grocy.tld";
  };
}

This configures a simple vhost using nginx which listens to grocy.tld with fully configured ACME/LE (this can be disabled by setting services.grocy.nginx.enableSSL to false). After the initial setup the credentials admin:admin can be used to login.

The application’s state is persisted at /var/lib/grocy/grocy.db in a sqlite3 database. The migration is applied when requesting the /-route of the application.

The configuration for grocy is located at /etc/grocy/config.php. By default, the following settings can be defined in the NixOS-configuration:

{ pkgs, ... }:
{
  services.grocy.settings = {
    # The default currency in the system for invoices etc.
    # Please note that exchange rates aren't taken into account, this
    # is just the setting for what's shown in the frontend.
    currency = "EUR";

    # The display language (and locale configuration) for grocy.
    culture = "de";

    calendar = {
      # Whether or not to show the week-numbers
      # in the calendar.
      showWeekNumber = true;

      # Index of the first day to be shown in the calendar (0=Sunday, 1=Monday,
      # 2=Tuesday and so on).
      firstDayOfWeek = 2;
    };
  };
}

If you want to alter the configuration file on your own, you can do this manually with an expression like this:

{ lib, ... }:
{
  environment.etc."grocy/config.php".text = lib.mkAfter ''
    // Arbitrary PHP code in grocy's configuration file
  '';
}

The following configuration sets up the PostgreSQL as database backend and binds GoToSocial to 127.0.0.1:8080, expecting to be run behind a HTTP proxy on gotosocial.example.com.

{
  services.gotosocial = {
    enable = true;
    setupPostgresqlDB = true;
    settings = {
      application-name = "My GoToSocial";
      host = "gotosocial.example.com";
      protocol = "https";
      bind-address = "127.0.0.1";
      port = 8080;
    };
  };
}

Please refer to the GoToSocial Documentation for additional configuration options.

Although it is possible to expose GoToSocial directly, it is common practice to operate it behind an HTTP reverse proxy such as nginx.

{
  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
  services.nginx = {
    enable = true;
    clientMaxBodySize = "40M";
    virtualHosts = with config.services.gotosocial.settings; {
      "${host}" = {
        enableACME = true;
        forceSSL = true;
        locations = {
          "/" = {
            recommendedProxySettings = true;
            proxyWebsockets = true;
            proxyPass = "http://${bind-address}:${toString port}";
          };
        };
      };
    };
  };
}

Please refer to SSL/TLS Certificates with ACME for details on how to provision an SSL/TLS certificate.

After the GoToSocial service is running, the gotosocial-admin utility can be used to manage users. In particular an administrative user can be created with

$ sudo gotosocial-admin account create --username <nickname> --email <email> --password <password>
$ sudo gotosocial-admin account confirm --username <nickname>
$ sudo gotosocial-admin account promote --username <nickname>

Check out the configuration docs to learn more. Use the following configuration to start a public instance of Glance locally:

{
  services.glance = {
    enable = true;
    settings = {
      pages = [
        {
          name = "Home";
          columns = [
            {
              size = "full";
              widgets = [
                { type = "calendar"; }
                {
                  type = "weather";
                  location = "Nivelles, Belgium";
                }
              ];
            }
          ];
        }
      ];
    };
    openFirewall = true;
  };
}

A minimal configuration using Let’s Encrypt for TLS certificates looks like this:

{
  services.discourse = {
    enable = true;
    hostname = "discourse.example.com";
    admin = {
      email = "[email protected]";
      username = "admin";
      fullName = "Administrator";
      passwordFile = "/path/to/password_file";
    };
    secretKeyBaseFile = "/path/to/secret_key_base_file";
  };
  security.acme.email = "[email protected]";
  security.acme.acceptTerms = true;
}

Provided a proper DNS setup, you’ll be able to connect to the instance at discourse.example.com and log in using the credentials provided in services.discourse.admin.

To set up TLS using a regular certificate and key on file, use the services.discourse.sslCertificate and services.discourse.sslCertificateKey options:

{
  services.discourse = {
    enable = true;
    hostname = "discourse.example.com";
    sslCertificate = "/path/to/ssl_certificate";
    sslCertificateKey = "/path/to/ssl_certificate_key";
    admin = {
      email = "[email protected]";
      username = "admin";
      fullName = "Administrator";
      passwordFile = "/path/to/password_file";
    };
    secretKeyBaseFile = "/path/to/secret_key_base_file";
  };
}

Discourse uses PostgreSQL to store most of its data. A database will automatically be enabled and a database and role created unless services.discourse.database.host is changed from its default of null or services.discourse.database.createLocally is set to false.

External database access can also be configured by setting services.discourse.database.host, services.discourse.database.username and services.discourse.database.passwordFile as appropriate. Note that you need to manually create a database called discourse (or the name you chose in services.discourse.database.name) and allow the configured database user full access to it.

In addition to the basic setup, you’ll want to configure an SMTP server Discourse can use to send user registration and password reset emails, among others. You can also optionally let Discourse receive email, which enables people to reply to threads and conversations via email.

A basic setup which assumes you want to use your configured hostname as email domain can be done like this:

{
  services.discourse = {
    enable = true;
    hostname = "discourse.example.com";
    sslCertificate = "/path/to/ssl_certificate";
    sslCertificateKey = "/path/to/ssl_certificate_key";
    admin = {
      email = "[email protected]";
      username = "admin";
      fullName = "Administrator";
      passwordFile = "/path/to/password_file";
    };
    mail.outgoing = {
      serverAddress = "smtp.emailprovider.com";
      port = 587;
      username = "[email protected]";
      passwordFile = "/path/to/smtp_password_file";
    };
    mail.incoming.enable = true;
    secretKeyBaseFile = "/path/to/secret_key_base_file";
  };
}

This assumes you have set up an MX record for the address you’ve set in hostname and requires proper SPF, DKIM and DMARC configuration to be done for the domain you’re sending from, in order for email to be reliably delivered.

If you want to use a different domain for your outgoing email (for example example.com instead of discourse.example.com) you should set services.discourse.mail.notificationEmailAddress and services.discourse.mail.contactEmailAddress manually.

Additional site settings and backend settings, for which no explicit NixOS options are provided, can be set in services.discourse.siteSettings and services.discourse.backendSettings respectively.

{
  services.discourse = {
    enable = true;
    hostname = "discourse.example.com";
    sslCertificate = "/path/to/ssl_certificate";
    sslCertificateKey = "/path/to/ssl_certificate_key";
    admin = {
      email = "[email protected]";
      username = "admin";
      fullName = "Administrator";
      passwordFile = "/path/to/password_file";
    };
    mail.outgoing = {
      serverAddress = "smtp.emailprovider.com";
      port = 587;
      username = "[email protected]";
      passwordFile = "/path/to/smtp_password_file";
    };
    mail.incoming.enable = true;
    siteSettings = {
      required = {
        title = "My Cats";
        site_description = "Discuss My Cats (and be nice plz)";
      };
      login = {
        enable_github_logins = true;
        github_client_id = "a2f6dfe838cb3206ce20";
        github_client_secret._secret = /run/keys/discourse_github_client_secret;
      };
    };
    backendSettings = {
      max_reqs_per_ip_per_minute = 300;
      max_reqs_per_ip_per_10_seconds = 60;
      max_asset_reqs_per_ip_per_10_seconds = 250;
      max_reqs_per_ip_mode = "warn+block";
    };
    secretKeyBaseFile = "/path/to/secret_key_base_file";
  };
}

You can install Discourse plugins using the services.discourse.plugins option. Pre-packaged plugins are provided in <your_discourse_package_here>.plugins. If you want the full suite of plugins provided through nixpkgs, you can also set the services.discourse.package option to pkgs.discourseAllPlugins.

Plugins can be built with the <your_discourse_package_here>.mkDiscoursePlugin function. Normally, it should suffice to provide a name and src attribute. If the plugin has Ruby dependencies, however, they need to be packaged in accordance with the Developing with Ruby section of the Nixpkgs manual and the appropriate gem options set in bundlerEnvArgs (normally gemdir is sufficient). A plugin’s Ruby dependencies are listed in its plugin.rb file as function calls to gem. To construct the corresponding Gemfile manually, run bundle init, then add the gem lines to it verbatim.

Much of the packaging can be done automatically by the nixpkgs/pkgs/servers/web-apps/discourse/update.py script - just add the plugin to the plugins list in the update_plugins function and run the script:

./update.py update-plugins

Some plugins provide site settings. Their defaults can be configured using services.discourse.siteSettings, just like regular site settings. To find the names of these settings, look in the config/settings.yml file of the plugin repo.

For example, to add the discourse-spoiler-alert and discourse-solved plugins, and disable discourse-spoiler-alert by default:

{
  services.discourse = {
    enable = true;
    hostname = "discourse.example.com";
    sslCertificate = "/path/to/ssl_certificate";
    sslCertificateKey = "/path/to/ssl_certificate_key";
    admin = {
      email = "[email protected]";
      username = "admin";
      fullName = "Administrator";
      passwordFile = "/path/to/password_file";
    };
    mail.outgoing = {
      serverAddress = "smtp.emailprovider.com";
      port = 587;
      username = "[email protected]";
      passwordFile = "/path/to/smtp_password_file";
    };
    mail.incoming.enable = true;
    plugins = with config.services.discourse.package.plugins; [
      discourse-spoiler-alert
      discourse-solved
    ];
    siteSettings = {
      plugins = {
        spoiler_enabled = false;
      };
    };
    secretKeyBaseFile = "/path/to/secret_key_base_file";
  };
}

At first, an application secret is needed, this can be generated with:

$ cat /dev/urandom | tr -dc a-zA-Z0-9 | fold -w 48 | head -n 1

After that, davis can be deployed like this:

{
  services.davis = {
    enable = true;
    hostname = "davis.example.com";
    mail = {
      dsn = "smtp://[email protected]:25";
      inviteFromAddress = "[email protected]";
    };
    adminLogin = "admin";
    adminPasswordFile = "/run/secrets/davis-admin-password";
    appSecretFile = "/run/secrets/davis-app-secret";
  };
}

This deploys Davis using a sqlite database running out of /var/lib/davis.

Logs can be found in /var/lib/davis/var/log/.

Configure ACME (https://nixos.org/manual/nixos/unstable/#module-security-acme). Use the following configuration to start a public instance of Castopod on castopod.example.com domain:

{
  networking.firewall.allowedTCPPorts = [
    80
    443
  ];
  services.castopod = {
    enable = true;
    database.createLocally = true;
    nginx.virtualHost = {
      serverName = "castopod.example.com";
      enableACME = true;
      forceSSL = true;
    };
  };
}

Go to https://castopod.example.com/cp-install to create superadmin account after applying the above configuration.

The Elixir configuration file required by Akkoma is generated automatically from services.akkoma.config. Secrets must be included from external files outside of the Nix store by setting the configuration option to an attribute set containing the attribute _secret – a string pointing to the file containing the actual value of the option.

For the mandatory configuration settings these secrets will be generated automatically if the referenced file does not exist during startup, unless disabled through services.akkoma.initSecrets.

The following configuration binds Akkoma to the Unix socket /run/akkoma/socket, expecting to be run behind a HTTP proxy on fediverse.example.com.

{
  services.akkoma.enable = true;
  services.akkoma.config = {
    ":pleroma" = {
      ":instance" = {
        name = "My Akkoma instance";
        description = "More detailed description";
        email = "[email protected]";
        registration_open = false;
      };

      "Pleroma.Web.Endpoint" = {
        url.host = "fediverse.example.com";
      };
    };
  };
}

Please refer to the configuration cheat sheet for additional configuration options.

After the Akkoma service is running, the administration utility can be used to manage users. In particular an administrative user can be created with

$ pleroma_ctl user new <nickname> <email> --admin --moderator --password <password>

Although it is possible to expose Akkoma directly, it is common practice to operate it behind an HTTP reverse proxy such as nginx.

{
  services.akkoma.nginx = {
    enableACME = true;
    forceSSL = true;
  };

  services.nginx = {
    enable = true;

    clientMaxBodySize = "16m";
    recommendedTlsSettings = true;
    recommendedOptimisation = true;
    recommendedGzipSettings = true;
  };
}

Please refer to SSL/TLS Certificates with ACME for details on how to provision an SSL/TLS certificate.

{
  # Enable nginx slice module distributed with Tengine
  services.nginx.package = pkgs.tengine;

  # Enable media proxy
  services.akkoma.config.":pleroma".":media_proxy" = {
    enabled = true;
    proxy_opts.redirect_on_failure = true;
  };

  # Adjust the persistent cache size as needed:
  #  Assuming an average object size of 128 KiB, around 1 MiB
  #  of memory is required for the key zone per GiB of cache.
  # Ensure that the cache directory exists and is writable by nginx.
  services.nginx.commonHttpConfig = ''
    proxy_cache_path /var/cache/nginx/cache/akkoma-media-cache
      levels= keys_zone=akkoma_media_cache:16m max_size=16g
      inactive=1y use_temp_path=off;
  '';

  services.akkoma.nginx = {
    locations."/proxy" = {
      proxyPass = "http://unix:/run/akkoma/socket";

      extraConfig = ''
        proxy_cache akkoma_media_cache;

        # Cache objects in slices of 1 MiB
        slice 1m;
        proxy_cache_key $host$uri$is_args$args$slice_range;
        proxy_set_header Range $slice_range;

        # Decouple proxy and upstream responses
        proxy_buffering on;
        proxy_cache_lock on;
        proxy_ignore_client_abort on;

        # Default cache times for various responses
        proxy_cache_valid 200 1y;
        proxy_cache_valid 206 301 304 1h;

        # Allow serving of stale items
        proxy_cache_use_stale error timeout invalid_header updating;
      '';
    };
  };
}

{
  services.akkoma.config.":pleroma".":mrf".policies = map (pkgs.formats.elixirConf { }).lib.mkRaw [
    "Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy"
  ];
}

{
  services.akkoma.config.":pleroma".":media_preview_proxy" = {
    enabled = true;
    thumbnail_max_width = 1920;
    thumbnail_max_height = 1080;
  };
}

Akkoma will be deployed with the akkoma-fe and admin-fe frontends by default. These can be modified by setting services.akkoma.frontends.

The following example overrides the primary frontend’s default configuration using a custom derivation.

{
  services.akkoma.frontends.primary.package =
    pkgs.runCommand "akkoma-fe"
      {
        config = builtins.toJSON {
          expertLevel = 1;
          collapseMessageWithSubject = false;
          stopGifs = false;
          replyVisibility = "following";
          webPushHideIfCW = true;
          hideScopeNotice = true;
          renderMisskeyMarkdown = false;
          hideSiteFavicon = true;
          postContentType = "text/markdown";
          showNavShortcuts = false;
        };
        nativeBuildInputs = with pkgs; [
          jq
          xorg.lndir
        ];
        passAsFile = [ "config" ];
      }
      ''
        mkdir $out
        lndir ${pkgs.akkoma-frontends.akkoma-fe} $out

        rm $out/static/config.json
        jq -s add ${pkgs.akkoma-frontends.akkoma-fe}/static/config.json ${config} \
          >$out/static/config.json
      '';
}

Akkoma comes with a number of modules to police federation with other ActivityPub instances. The most valuable for typical users is the :mrf_simple module which allows limiting federation based on instance hostnames.

This configuration snippet provides an example on how these can be used. Choosing an adequate federation policy is not trivial and entails finding a balance between connectivity to the rest of the fediverse and providing a pleasant experience to the users of an instance.

{
  services.akkoma.config.":pleroma" = with (pkgs.formats.elixirConf { }).lib; {
    ":mrf".policies = map mkRaw [ "Pleroma.Web.ActivityPub.MRF.SimplePolicy" ];

    ":mrf_simple" = {
      # Tag all media as sensitive
      media_nsfw = mkMap { "nsfw.weird.kinky" = "Untagged NSFW content"; };

      # Reject all activities except deletes
      reject = mkMap {
        "kiwifarms.cc" = "Persistent harassment of users, no moderation";
      };

      # Force posts to be visible by followers only
      followers_only = mkMap {
        "beta.birdsite.live" = "Avoid polluting timelines with Twitter posts";
      };
    };
  };
}

This example strips GPS and location metadata from uploads, deduplicates them and anonymises the the file name.

{
  services.akkoma.config.":pleroma"."Pleroma.Upload".filters =
    map (pkgs.formats.elixirConf { }).lib.mkRaw
      [
        "Pleroma.Upload.Filter.Exiftool"
        "Pleroma.Upload.Filter.Dedupe"
        "Pleroma.Upload.Filter.AnonymizeFilename"
      ];
}

Pleroma instances can be migrated to Akkoma either by copying the database and upload data or by pointing Akkoma to the existing data. The necessary database migrations are run automatically during startup of the service.

The configuration has to be copy‐edited manually.

Depending on the size of the database, the initial migration may take a long time and exceed the startup timeout of the system manager. To work around this issue one may adjust the startup timeout systemd.services.akkoma.serviceConfig.TimeoutStartSec or simply run the migrations manually:

pleroma_ctl migrate

# Create a copy of the database
nix-shell -p postgresql --run 'createdb -T pleroma akkoma'

# Copy upload data
mkdir /var/lib/akkoma
cp -R --reflink=auto /var/lib/pleroma/uploads /var/lib/akkoma/

# Delete original database
nix-shell -p postgresql --run 'dropdb pleroma'

# Delete original Pleroma state
rm -r /var/lib/pleroma

{
  # Adjust these settings according to the database name and upload directory path used by Pleroma
  services.akkoma.config.":pleroma"."Pleroma.Repo".database = "pleroma";
  services.akkoma.config.":pleroma".":instance".upload_dir = "/var/lib/pleroma/uploads";
}

To enable a Kerberos server:

{
  security.krb5 = {
    # Here you can choose between the MIT and Heimdal implementations.
    package = pkgs.krb5;
    # package = pkgs.heimdal;

    # Optionally set up a client on the same machine as the server
    enable = true;
    settings = {
      libdefaults.default_realm = "EXAMPLE.COM";
      realms."EXAMPLE.COM" = {
        kdc = "kerberos.example.com";
        admin_server = "kerberos.example.com";
      };
    };
  };

  services.kerberos-server = {
    enable = true;
    settings = {
      realms."EXAMPLE.COM" = {
        acl = [
          {
            principal = "adminuser";
            access = [
              "add"
              "cpw"
            ];
          }
        ];
      };
    };
  };
}

Note the version number in the URLs, it may be different for the latest version.

the minimum to start meilisearch is

{ services.meilisearch.enable = true; }

this will start the http server included with meilisearch on port 7700.

test with curl -X GET 'http://localhost:7700/health'

you first need to add documents to an index before you can search for documents.