Skip to content

recommend remote builders as substituters #1161

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

recommend remote builders as substituters #1161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions source/guides/recipes/add-binary-cache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
(custom-binary-cache)=
# Configure Nix to use a custom binary cache

Nix can be configured to use a binary cache with the [`substituters`](https://nix.dev/manual/nix/2.21/command-ref/conf-file.html#conf-substituters) and [`trusted-public-keys`](https://nix.dev/manual/nix/2.21/command-ref/conf-file.html#conf-trusted-public-keys) settings, either exclusively or in addition to cache.nixos.org.
Nix can be configured to use a binary cache with the [`substituters`](https://nix.dev/manual/nix/latest/command-ref/conf-file.html#conf-substituters) and [`trusted-public-keys`](https://nix.dev/manual/nix/latest/command-ref/conf-file.html#conf-trusted-public-keys) settings, either exclusively or in addition to cache.nixos.org.

:::{tip}
Follow the tutorial to [set up an HTTP binary cache](setup-http-binary-cache) and create a key pair for signing store objects.
:::

For example, given a binary cache at `https://example.org` with public key `My56...Q==%`, and some derivation in `default.nix`, make Nix exclusively use that cache once by passing [settings as command line flags](https://nix.dev/manual/nix/2.21/command-ref/conf-file#command-line-flags):
For example, given a binary cache at `https://example.org` with public key `My56...Q==%`, and some derivation in `default.nix`, make Nix exclusively use that cache once by passing [settings as command line flags](https://nix.dev/manual/nix/latest/command-ref/conf-file#command-line-flags):

```shell-session
$ nix-build --substituters https://example.org --trusted-public-keys example.org:My56...Q==%
```

To permanently use the custom cache in addition to the public cache, add to the [Nix configuration file](https://nix.dev/manual/nix/2.21/command-ref/conf-file#configuration-file):
To permanently configure trying the custom cache before the public cache, add it as `extra-substiters` with lower `priority` value to the [Nix configuration file](https://nix.dev/manual/nix/latest/command-ref/conf-file#configuration-file):

```shell-session
$ echo "extra-substituters = https://example.org" >> /etc/nix/nix.conf
$ echo "extra-substituters = https://example.org?priority=30" >> /etc/nix/nix.conf
$ echo "extra-trusted-public-keys = example.org:My56...Q==%" >> /etc/nix/nix.conf
```

Expand All @@ -33,9 +33,13 @@ On NixOS, Nix is configured through the [`nix.settings`](https://search.nixos.or
```nix
{ ... }: {
nix.settings = {
substituters = [ "https://example.org" ];
substituters = [ "https://example.org?priority=30" ];
trusted-public-keys = [ "example.org:My56...Q==%" ];
};
}
```
::::

:::{tip}
Use [remote build machines](distributed-build-setup-tutorial) as preferred binary caches to reduce your external traffic.
:::
6 changes: 5 additions & 1 deletion source/tutorials/nixos/distributed-builds-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,7 @@ To maximise parallelism, enable automatic garbage collection, and prevent Nix bu
```

:::{tip}
Refer to the [Nix reference manual](https://nix.dev/manual/nix/2.23/command-ref/conf-file) for details on the options available in [`nix.settings`](https://search.nixos.org/options?show=nix.settings).
Refer to the [Nix reference manual](https://nix.dev/manual/nix/latest/command-ref/conf-file) for details on the options available in [`nix.settings`](https://search.nixos.org/options?show=nix.settings).
:::

Remote builders can have different performance characteristics.
Expand All @@ -314,6 +314,10 @@ Set the `nix.buildMachines.*.publicHostKey` field to each remote builder's publi
To set up multiple builders, repeat the instructions in the [](set-up-remote-builder) section for each remote builder.
Add all new remote builders to the `nix.buildMachines` attribute shown in the [](set-up-distributed-builds) section.

:::{tip}
Configure remote build machines to [host a binary cache](setup-http-binary-cache) and use them as [preferred binary caches](custom-binary-cache) to reduce your external traffic.
:::

## Alternatives

- [nixbuild.net](https://nixbuild.net) - Nix remote builders as a service
Expand Down