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

See secretsMap in mkEffect

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.

runNixOS

See also

`runNixOS`