Example NixOS servers deployment

Quick start

Install Nix (learn more about this installer)

curl --proto '=https' --tlsv1.2 -sSf \
    -L https://install.determinate.systems/nix \
    | sh -s -- install

and run nix develop to launch development environment.

Development workflow

Create configuration

1. Create reusable configuration profiles in profiles directory

Create a new host

1. Add new host to nixosConfiguration and apps outputs in flake.nix file

2. Create host declaration in hosts/<hostname> directory (use hosts/server1 as example)

3. Test configuration

nix flake check --no-build

1. Test server in VM

nix run .#<hostname>

Add integration test

1. Add new test to checks output in flake.nix file

2. Create test script in tests/<test-name>.nix file

3. Run test

nix flake check`

Explore server configuration (optional)

1. Launch interactive environment

  nix repl ./repl.nix --argstr hostname <hostname>"

1. Print configuration value

  :p config.<option>

For example, print a list of enabled ssh ports

  :p config.services.openssh.ports

or print full admin user configuration

  :p config.users.users.admin

Enable port forwarding (optional)

If needed, port forwarding can be configured in profiles/development.nix file. This file must be included in host declaration file hosts/<hostname>/default.nix (see: hosts/server1/default.nix for example).

Secrets management

1. Create identities (users and/or systems able to use secrets) and secrets in secrets/secrets.nix file

2. Create a encrypted file for each secret

  nix develop
  agenix -e <SECRET-NAME>.age

1. Use secret in NixOS module (see: profiles/secrets.nix for example)

For more information check out Agenix tutorial.

Deployment

1. TODO - nixos-anywhere

Maintenance

System upgrade

1. Merge flake inputs update PR created by flake-update workflow

2. Update deploy tag using utils/release.sh script

3. Wait for system update is performed automatically at 1am (see profiles/auto-upgrade.nix)

Other

• Get system version (run on server)

  nixos-version --json