runNixOS

runNixOS :: AttrSet → Effect

Deploy a NixOS configuration to a machine over SSH.

Example (Flakes):

hci-effects.runNixOS {
  name = "deploy";
  configuration = self.nixosConfigurations.zeus;
  ssh.destination = "[email protected]";
  system = "aarch64-linux";
  secretsMap.ssh = "deploy-ssh";
  userSetupScript = ''
    writeSSHKey
    cat >>~/.ssh/known_hosts <<EOF
    zeus.local ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=
    EOF
  '';
}
This function has a how-to guide. See Deploy a NixOS Machine for a step by step guide to deploy to an existing NixOS machine.

Parameters

buildOnDestination

Default: value of ssh.buildOnDestination, which defaults to false.

Overrides ssh.buildOnDestination. Defer builds to the destination host instead of pre-building in CI.

config

You may want to use configuration instead.

This option allows you to insert a custom NixOS invocation, in case your configuration has already been invoked with the module system.

When this option is set, system, configuration and nixpkgs are ignored.

configuration

A NixOS configuration or module.

Example: configuration = ./configuration.nix;

Example (Flakes): configuration = self.nixosConfigurations.foo;

Required, unless you set xref:param-config, which is not the preferred solution.

When this option is set to a pre-evaluated configuration, as in the latter example, system, configuration and nixpkgs are ignored.

nixpkgs

Required when configuration is a module or file.

Path of the Nixpkgs sources to use. These also include the NixOS sources.

Default: pkgs.path, where pkgs is the Nixpkgs invocation that included the effects overlay.

secretsMap

Example:

    secretsMap.ssh = "myuser-ssh";

ssh

See the named arguments in ssh. Example:

  ssh.destination = "[email protected]";

system

Optional, legacy.

Preferably, this is set in the configuration itself, in nixpkgs.hostPlatform.

nixos-generate-config sets that option automatically in hardware-configuration.nix.

userSetupScript

Example:

    userSetupScript = ''
      writeSSHKey
      cat >>~/.ssh/known_hosts <<EOF
      203.0.113.2 ecdsa-sha2-nistp256 AA.....pw=
      EOF
    '';

See:

Return value

An effect that switches the NixOS system as configured.

The effect has the following attributes in addition to the attributes returned by mkEffect.

config

The config parameter of the module system. This can be used to inspect the system configuration before committing it. For example:

nix repl --file ci.nix
nix-repl> my-host.prebuilt.config.services.postgresql.enable
false

prebuilt

A derivation representing the built system configuration.

prebuilt.config

Same as config.

See also

  • Deploy a NixOS Machine — a step by step guide to deploy to an existing NixOS machine

  • runNixOps — provision interrelated machine configurations and other cloud resources

  • runArion — deploy services to Docker using NixOS, Nix or Docker-based images

  • runNixDarwin — the macOS equivalent for deploying to a single Apple machine configured with nix-darwin