forked from lix-project/lix
142 lines
5.4 KiB
Markdown
142 lines
5.4 KiB
Markdown
|
# Remote Builds
|
|||
|
|
|||
|
Nix supports remote builds, where a local Nix installation can forward
|
|||
|
Nix builds to other machines. This allows multiple builds to be
|
|||
|
performed in parallel and allows Nix to perform multi-platform builds in
|
|||
|
a semi-transparent way. For instance, if you perform a build for a
|
|||
|
`x86_64-darwin` on an `i686-linux` machine, Nix can automatically
|
|||
|
forward the build to a `x86_64-darwin` machine, if available.
|
|||
|
|
|||
|
To forward a build to a remote machine, it’s required that the remote
|
|||
|
machine is accessible via SSH and that it has Nix installed. You can
|
|||
|
test whether connecting to the remote Nix instance works, e.g.
|
|||
|
|
|||
|
$ nix ping-store --store ssh://mac
|
|||
|
|
|||
|
will try to connect to the machine named `mac`. It is possible to
|
|||
|
specify an SSH identity file as part of the remote store URI, e.g.
|
|||
|
|
|||
|
$ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key
|
|||
|
|
|||
|
Since builds should be non-interactive, the key should not have a
|
|||
|
passphrase. Alternatively, you can load identities ahead of time into
|
|||
|
`ssh-agent` or `gpg-agent`.
|
|||
|
|
|||
|
If you get the error
|
|||
|
|
|||
|
bash: nix-store: command not found
|
|||
|
error: cannot connect to 'mac'
|
|||
|
|
|||
|
then you need to ensure that the PATH of non-interactive login shells
|
|||
|
contains Nix.
|
|||
|
|
|||
|
> **Warning**
|
|||
|
>
|
|||
|
> If you are building via the Nix daemon, it is the Nix daemon user
|
|||
|
> account (that is, `root`) that should have SSH access to the remote
|
|||
|
> machine. If you can’t or don’t want to configure `root` to be able to
|
|||
|
> access to remote machine, you can use a private Nix store instead by
|
|||
|
> passing e.g. `--store ~/my-nix`.
|
|||
|
|
|||
|
The list of remote machines can be specified on the command line or in
|
|||
|
the Nix configuration file. The former is convenient for testing. For
|
|||
|
example, the following command allows you to build a derivation for
|
|||
|
`x86_64-darwin` on a Linux machine:
|
|||
|
|
|||
|
$ uname
|
|||
|
Linux
|
|||
|
|
|||
|
$ nix build \
|
|||
|
'(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \
|
|||
|
--builders 'ssh://mac x86_64-darwin'
|
|||
|
[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac
|
|||
|
|
|||
|
$ cat ./result
|
|||
|
Darwin
|
|||
|
|
|||
|
It is possible to specify multiple builders separated by a semicolon or
|
|||
|
a newline, e.g.
|
|||
|
|
|||
|
```
|
|||
|
--builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
|
|||
|
```
|
|||
|
|
|||
|
Each machine specification consists of the following elements, separated
|
|||
|
by spaces. Only the first element is required. To leave a field at its
|
|||
|
default, set it to `-`.
|
|||
|
|
|||
|
1. The URI of the remote store in the format
|
|||
|
`ssh://[username@]hostname`, e.g. `ssh://nix@mac` or `ssh://mac`.
|
|||
|
For backward compatibility, `ssh://` may be omitted. The hostname
|
|||
|
may be an alias defined in your `~/.ssh/config`.
|
|||
|
|
|||
|
2. A comma-separated list of Nix platform type identifiers, such as
|
|||
|
`x86_64-darwin`. It is possible for a machine to support multiple
|
|||
|
platform types, e.g., `i686-linux,x86_64-linux`. If omitted, this
|
|||
|
defaults to the local platform type.
|
|||
|
|
|||
|
3. The SSH identity file to be used to log in to the remote machine. If
|
|||
|
omitted, SSH will use its regular identities.
|
|||
|
|
|||
|
4. The maximum number of builds that Nix will execute in parallel on
|
|||
|
the machine. Typically this should be equal to the number of CPU
|
|||
|
cores. For instance, the machine `itchy` in the example will execute
|
|||
|
up to 8 builds in parallel.
|
|||
|
|
|||
|
5. The “speed factor”, indicating the relative speed of the machine. If
|
|||
|
there are multiple machines of the right type, Nix will prefer the
|
|||
|
fastest, taking load into account.
|
|||
|
|
|||
|
6. A comma-separated list of *supported features*. If a derivation has
|
|||
|
the `requiredSystemFeatures` attribute, then Nix will only perform
|
|||
|
the derivation on a machine that has the specified features. For
|
|||
|
instance, the attribute
|
|||
|
|
|||
|
requiredSystemFeatures = [ "kvm" ];
|
|||
|
|
|||
|
will cause the build to be performed on a machine that has the `kvm`
|
|||
|
feature.
|
|||
|
|
|||
|
7. A comma-separated list of *mandatory features*. A machine will only
|
|||
|
be used to build a derivation if all of the machine’s mandatory
|
|||
|
features appear in the derivation’s `requiredSystemFeatures`
|
|||
|
attribute..
|
|||
|
|
|||
|
For example, the machine specification
|
|||
|
|
|||
|
nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 1 kvm
|
|||
|
nix@itchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 2
|
|||
|
nix@poochie.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 1 2 kvm benchmark
|
|||
|
|
|||
|
specifies several machines that can perform `i686-linux` builds.
|
|||
|
However, `poochie` will only do builds that have the attribute
|
|||
|
|
|||
|
requiredSystemFeatures = [ "benchmark" ];
|
|||
|
|
|||
|
or
|
|||
|
|
|||
|
requiredSystemFeatures = [ "benchmark" "kvm" ];
|
|||
|
|
|||
|
`itchy` cannot do builds that require `kvm`, but `scratchy` does support
|
|||
|
such builds. For regular builds, `itchy` will be preferred over
|
|||
|
`scratchy` because it has a higher speed factor.
|
|||
|
|
|||
|
Remote builders can also be configured in `nix.conf`, e.g.
|
|||
|
|
|||
|
builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd
|
|||
|
|
|||
|
Finally, remote builders can be configured in a separate configuration
|
|||
|
file included in `builders` via the syntax `@file`. For example,
|
|||
|
|
|||
|
builders = @/etc/nix/machines
|
|||
|
|
|||
|
causes the list of machines in `/etc/nix/machines` to be included. (This
|
|||
|
is the default.)
|
|||
|
|
|||
|
If you want the builders to use caches, you likely want to set the
|
|||
|
option [`builders-use-substitutes`](#conf-builders-use-substitutes) in
|
|||
|
your local `nix.conf`.
|
|||
|
|
|||
|
To build only on remote builders and disable building on the local
|
|||
|
machine, you can use the option `--max-jobs 0`.
|