runNixOS

runNixOS :: AttrSet → Effect

Deploy a NixOS configuration to a machine.

Parameters

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 file or module.

Example: configuration = ./configuration.nix;

Required, unless you invoke the module system yourself via xref:param-config.

nixpkgs

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";

sshDestination

Hostname to SSH to.

"destination, which may be specified as either [[email protected]]hostname or a URI of the form ssh://[[email protected]]hostname[:port.]"
— `man 1 ssh`

system

The Nix system of the machine to deploy.

Example: system = "x86_64-linux";

Example: system = "aarch64-linux";

Required, unless you pass the module system result via xref:param-config.

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