Binary Cache - Revision history

Mdaniels5757: fix some syntaxhighlight errors

2026-05-03T01:42:18Z

fix some syntaxhighlight errors

← Older revision		Revision as of 01:42, 3 May 2026
Line 239:		Line 239:
	};		};
	};		};
	</syntaxhighlight>As described on [https://search.nixos.org/options?show=nix.settings.substituters&type=packages&query=substituters search.nixos.org] by default <nowiki>https://cache.nixos.org/</nowiki> is added to the substituters. You may need to use lib.mkForce to override this and ensure your substituter is the primary choice.<syntaxhighlight>		</syntaxhighlight>As described on [https://search.nixos.org/options?show=nix.settings.substituters&type=packages&query=substituters search.nixos.org] by default <nowiki>https://cache.nixos.org/</nowiki> is added to the substituters. You may need to use lib.mkForce to override this and ensure your substituter is the primary choice.<syntaxhighlight lang="nix">
	# /etc/nixos/configuration.nix		# /etc/nixos/configuration.nix

Line 297:		Line 297:
	You can place a hint to your binary cache in your Flake so when someone builds an output of your Flake, the nix command will ask interactively to trust the specified binary cache.		You can place a hint to your binary cache in your Flake so when someone builds an output of your Flake, the nix command will ask interactively to trust the specified binary cache.

	<syntaxHighlight lang=nix>		<syntaxHighlight lang="nix">
	{		{
	nixConfig = {		nixConfig = {

Drupol: /* Setting up a binary cache with attic and caddy */

2026-03-27T18:22:18Z

Setting up a binary cache with attic and caddy

← Older revision		Revision as of 18:22, 27 March 2026
Line 23:		Line 23:
	};		};

	# Inspired from https://github.com/phanirithvij/system/blob/main/nixos/applications/nix/selfhosted/proxy-cache.nix		# Inspired from:
			# 1. https://github.com/phanirithvij/system/blob/main/nixos/applications/nix/selfhosted/proxy-cache.nix
			# 2. https://github.com/rnl-dei/nixrnl/blob/master/profiles/proxy-cache.nix
	caddy = {		caddy = {
	enable = true;		enable = true;

Drupol: /* Setting up a binary cache with attic and caddy */

2026-03-27T18:11:24Z

Setting up a binary cache with attic and caddy

← Older revision		Revision as of 18:11, 27 March 2026
Line 4:		Line 4:

	== Setting up a binary cache with attic and caddy ==		== Setting up a binary cache with attic and caddy ==
	Here's a snippet enabling Attic and Caddy.		Here's a snippet enabling [https://github.com/zhaofengli/attic Attic] and [https://caddyserver.com/ Caddy].

	Please refer to the [https://docs.attic.rs/ Attic documentation] to set it up correctly.<syntaxhighlight lang="nix" line="1">		Please refer to the [https://docs.attic.rs/ Attic documentation] to set it up correctly. The goal here is to show how those two services can be used together to provide a solid solution.<syntaxhighlight lang="nix" line="1">
	{		{
	networking.firewall = {		networking.firewall = {

Drupol: Setup a binary cache with Attic and Caddy

2026-03-27T18:05:40Z

Setup a binary cache with Attic and Caddy

← Older revision		Revision as of 18:05, 27 March 2026
Line 2:		Line 2:

	A binary cache builds Nix packages and caches the result for other machines. Any machine with Nix installed can be a binary cache for another one, no matter the operating system.		A binary cache builds Nix packages and caches the result for other machines. Any machine with Nix installed can be a binary cache for another one, no matter the operating system.

			== Setting up a binary cache with attic and caddy ==
			Here's a snippet enabling Attic and Caddy.

			Please refer to the [https://docs.attic.rs/ Attic documentation] to set it up correctly.<syntaxhighlight lang="nix" line="1">
			{
			networking.firewall = {
			allowedTCPPorts = [ 8080 ];
			};

			services = {
			atticd = {
			enable = true;
			settings = {
			listen = "127.0.0.1:8081";
			};
			# Path to an EnvironmentFile containing required environment variables:
			# ATTIC_SERVER_TOKEN_RS256_SECRET_BASE64: The base64-encoded RSA PEM PKCS1 of the RS256 JWT secret. Generate it with openssl genrsa -traditional 4096 \| base64 -w0.
			environmentFile = "/root/.attic-env-file";
			};

			# Inspired from https://github.com/phanirithvij/system/blob/main/nixos/applications/nix/selfhosted/proxy-cache.nix
			caddy = {
			enable = true;

			package = pkgs.caddy.withPlugins {
			plugins = [ "github.com/caddyserver/cache-handler@v0.16.0" ];
			hash = "sha256-CecAx6KelOHEDiOKDTKLlDcnWtRNnDzBw1AzgN5JaFw=";
			};

			globalConfig = ''
			order cache before rewrite
			cache {
			# Global default cache duration (if not overridden below)
			ttl 1h
			log_level debug
			}
			'';

			virtualHosts.":8080" = {
			extraConfig = ''
			log {
			format console
			}

			# Nix cache info endpoint
			@nix_cache_info path /nix-cache-info
			handle @nix_cache_info {
			header Cache-Control "public, max-age=300"

			# 2. Tell Caddy's internal cache to hold this for 5 minutes
			cache {
			ttl 300s
			}

			reverse_proxy https://cache.nixos.org {
			header_up Host cache.nixos.org
			}
			}

			# NAR files (the actual packages)
			@nar path /nar/*
			handle @nar {
			header Cache-Control "public, max-age=31536000, immutable"

			# Cache the actual nar packages for a year
			cache {
			ttl 8760h
			}

			reverse_proxy https://cache.nixos.org {
			header_up Host cache.nixos.org
			}
			}

			# Narinfo files (metadata about packages)
			@narinfo path_regexp ^/[^/]+\.narinfo$
			handle @narinfo {
			header Cache-Control "public, max-age=86400"

			# Narinfo can change, so cache them locally for 24 hours
			cache {
			ttl 24h
			}

			reverse_proxy https://cache.nixos.org {
			header_up Host cache.nixos.org
			}
			}

			# Fallback for other requests
			handle {
			# We omit the `cache` directive here so Caddy doesn't interfere
			# with Attic's API operations or package pushing (PUT/POST requests).
			reverse_proxy 127.0.0.1:8081
			}
			'';
			};
			};
			};
			};

			</syntaxhighlight>

	== Setting up a binary cache with nix-serve and nginx ==		== Setting up a binary cache with nix-serve and nginx ==

Drupol at 18:01, 27 March 2026

2026-03-27T18:01:17Z

← Older revision		Revision as of 18:01, 27 March 2026
Line 3:		Line 3:
	A binary cache builds Nix packages and caches the result for other machines. Any machine with Nix installed can be a binary cache for another one, no matter the operating system.		A binary cache builds Nix packages and caches the result for other machines. Any machine with Nix installed can be a binary cache for another one, no matter the operating system.

	== Setting up a binary cache ==		== Setting up a binary cache with nix-serve and nginx ==

	This tutorial explains how to setup a machine as a binary cache for other machines, serving the nix store on TCP port 80 with signing turned on. It assumes that an {{ic\|[[nginx]]}} service is already running, that port 80 is open,<ref group="cf."> {{manual:nixos\|sec=#sec-firewall\|chapter=11.5. Firewall}}</ref> and that the hostname {{ic\|binarycache.example.com}} resolves to the server.<ref group="cf.">{{nixos:option\|networking.hostName}}</ref>		This tutorial explains how to setup a machine as a binary cache for other machines, serving the nix store on TCP port 80 with signing turned on. It assumes that an {{ic\|[[nginx]]}} service is already running, that port 80 is open,<ref group="cf."> {{manual:nixos\|sec=#sec-firewall\|chapter=11.5. Firewall}}</ref> and that the hostname {{ic\|binarycache.example.com}} resolves to the server.<ref group="cf.">{{nixos:option\|networking.hostName}}</ref>

Daemonfire: I think this https://discourse.nixos.org/t/garnix-blog-stop-trusting-nix-caches/70177 raises a valid point that should be added to the wiki to educate people about the implications.

2025-10-02T10:12:00Z

I think this https://discourse.nixos.org/t/garnix-blog-stop-trusting-nix-caches/70177 raises a valid point that should be added to the wiki to educate people about the implications.

← Older revision		Revision as of 10:12, 2 October 2025
Line 113:		Line 113:

	To configure Nix to use a certain binary cache, refer to the Nix manual.<ref group="cf.">[https://nixos.org/nix/manual/#ch-files Nix Manual, 21. Files]</ref> Add the binary cache as substituter (see the option {{ic\|substituters}}) and the public key to the trusted keys (see {{ic\|trusted-public-keys}}).		To configure Nix to use a certain binary cache, refer to the Nix manual.<ref group="cf.">[https://nixos.org/nix/manual/#ch-files Nix Manual, 21. Files]</ref> Add the binary cache as substituter (see the option {{ic\|substituters}}) and the public key to the trusted keys (see {{ic\|trusted-public-keys}}).
			{{Warning\|When adding a third-party binary cache you now trust all packages being served from that cache. Make sure this is a conscious decision. Trusting arbitrary caches can open you up to suppply chain attacks.
	{{tip\|If you are facing problems with derivations not being in a cache, try switching to a release version. Most caches will have many derivations for a specific release.}}		For more context: https://discourse.nixos.org/t/garnix-blog-stop-trusting-nix-caches/70177 (if source unavailable, https://web.archive.org/web/20251001172145/https://garnix.io/blog/stop-trusting-nix-caches)}}{{tip\|If you are facing problems with derivations not being in a cache, try switching to a release version. Most caches will have many derivations for a specific release.}}

	Permanent use of binary cache:		Permanent use of binary cache:

Pigs: move suggestion about using a release version into the usage section

2025-05-12T05:57:20Z

move suggestion about using a release version into the usage section

← Older revision		Revision as of 05:57, 12 May 2025
Line 2:		Line 2:

	A binary cache builds Nix packages and caches the result for other machines. Any machine with Nix installed can be a binary cache for another one, no matter the operating system.		A binary cache builds Nix packages and caches the result for other machines. Any machine with Nix installed can be a binary cache for another one, no matter the operating system.

	~~If you are facing problems with derivations not being in a cache, try switching to a release version. Most caches will have many derivations for a specific release.~~

	== Setting up a binary cache ==		== Setting up a binary cache ==
Line 115:		Line 113:

	To configure Nix to use a certain binary cache, refer to the Nix manual.<ref group="cf.">[https://nixos.org/nix/manual/#ch-files Nix Manual, 21. Files]</ref> Add the binary cache as substituter (see the option {{ic\|substituters}}) and the public key to the trusted keys (see {{ic\|trusted-public-keys}}).		To configure Nix to use a certain binary cache, refer to the Nix manual.<ref group="cf.">[https://nixos.org/nix/manual/#ch-files Nix Manual, 21. Files]</ref> Add the binary cache as substituter (see the option {{ic\|substituters}}) and the public key to the trusted keys (see {{ic\|trusted-public-keys}}).

			{{tip\|If you are facing problems with derivations not being in a cache, try switching to a release version. Most caches will have many derivations for a specific release.}}

	Permanent use of binary cache:		Permanent use of binary cache:

Mksafavi: /* Binary cache hint in Flakes */

2025-03-19T00:19:08Z

Binary cache hint in Flakes

@@ Line 207: / Line 207: @@
+}
 </syntaxHighlight>
 == Populating a binary cache ==

Mic92: update nixos version

2024-12-03T08:39:58Z

update nixos version

← Older revision		Revision as of 08:39, 3 December 2024
Line 221:		Line 221:
	It is also possible to sign all the packages that already exist in the nix store of the machine serving the binary cache to make them immediately available.		It is also possible to sign all the packages that already exist in the nix store of the machine serving the binary cache to make them immediately available.
	<code>$ nix store sign --extra-experimental-features nix-command --all --key-file /var/cache-priv-key.pem</code>		<code>$ nix store sign --extra-experimental-features nix-command --all --key-file /var/cache-priv-key.pem</code>
	Note : As of NixOS 24.05 {{ic\|--extra-experimental-features nix-command}} is required for {{ic\|store sign}} if this is not in your configuration.nix.		Note : As of NixOS 24.11 {{ic\|--extra-experimental-features nix-command}} is required for {{ic\|store sign}} if this is not in your configuration.nix.

	== Hosted binary cache ==		== Hosted binary cache ==

Fsbof: Removed extra-substituters as not available since 22.05, Added Signing Existing Packages, Added Command Line Options

2024-07-01T10:10:24Z

Removed extra-substituters as not available since 22.05, Added Signing Existing Packages, Added Command Line Options

← Older revision		Revision as of 10:10, 1 July 2024
Line 114:		Line 114:
	== Using a binary cache ==		== Using a binary cache ==

	To configure Nix to use a certain binary cache, refer to the Nix manual.<ref group="cf.">[https://nixos.org/nix/manual/#ch-files Nix Manual, 21. Files]</ref> Add the binary cache as substituter (see the ~~options~~ {{ic\|~~substituters}} and {{ic\|extra-~~substituters}}) and the public key to the trusted keys (see {{ic\|trusted-public-keys}}).		To configure Nix to use a certain binary cache, refer to the Nix manual.<ref group="cf.">[https://nixos.org/nix/manual/#ch-files Nix Manual, 21. Files]</ref> Add the binary cache as substituter (see the option {{ic\|substituters}}) and the public key to the trusted keys (see {{ic\|trusted-public-keys}}).

	Permanent use of binary cache:		Permanent use of binary cache:
Line 134:		Line 134:
	};		};
	};		};
	</syntaxhighlight>		</syntaxhighlight>As described on [https://search.nixos.org/options?show=nix.settings.substituters&type=packages&query=substituters search.nixos.org] by default <nowiki>https://cache.nixos.org/</nowiki> is added to the substituters. You may need to use lib.mkForce to override this and ensure your substituter is the primary choice.<syntaxhighlight>
			# /etc/nixos/configuration.nix


	{{Warning\|Keys that are entered incorrectly or are otherwise invalid, aside from preventing you from benefiting from the cached derivations, may also prevent you from rebuilding your system. This is most likely to occur after garbage collection (e.g., via <code>nix-collect-garbage -d</code>). Consult [https://github.com/NixOS/nix/issues/8271 NixOS/nix#8271] for additional details and a workaround.}}		{ config, lib, pkgs, ... }:

			{
			nix = {
			settings = {
			substituters = lib.mkForce [
			"http://binarycache.example.com"
			];
			trusted-public-keys = [
			"binarycache.example.com-1:dsafdafDFW123fdasfa123124FADSAD"
			];
			};
			};
			}
			</syntaxhighlight>{{Warning\|Keys that are entered incorrectly or are otherwise invalid, aside from preventing you from benefiting from the cached derivations, may also prevent you from rebuilding your system. This is most likely to occur after garbage collection (e.g., via <code>nix-collect-garbage -d</code>). Consult [https://github.com/NixOS/nix/issues/8271 NixOS/nix#8271] for additional details and a workaround.}}

	Temporary use of binary cache:		Temporary use of binary cache:
Line 201:		Line 217:
	</syntaxhighlight>		</syntaxhighlight>
	For details see the [https://nixos.org/manual/nix/stable/package-management/sharing-packages.html Sharing Packages Between Machines] in the Nix manual.		For details see the [https://nixos.org/manual/nix/stable/package-management/sharing-packages.html Sharing Packages Between Machines] in the Nix manual.

			== Signing Existing Packages ==
			It is also possible to sign all the packages that already exist in the nix store of the machine serving the binary cache to make them immediately available.
			<code>$ nix store sign --extra-experimental-features nix-command --all --key-file /var/cache-priv-key.pem</code>
			Note : As of NixOS 24.05 {{ic\|--extra-experimental-features nix-command}} is required for {{ic\|store sign}} if this is not in your configuration.nix.

	== Hosted binary cache ==		== Hosted binary cache ==
Line 245:		Line 266:
	curl https://cache.nixos.org/$(readlink -f $(which bash) \| cut -c12-43).narinfo		curl https://cache.nixos.org/$(readlink -f $(which bash) \| cut -c12-43).narinfo
	</pre>		</pre>

			== Command Line Options ==
			It is also possible to pass {{ic\|substituters}} and {{ic\|trusted-public-keys}} on the command line if they are not in {{ic\|configuration.nix}} or you want to use a particular binary cache server.
			$ nix-build --option substituters "<nowiki>http://binarycache.example.com</nowiki>" --option trusted-public-keys "binarycache.example.com-1:dsafdafDFW123fdasfa123124FADSAD" '<nixpkgs>' -A pkgs.PACKAGE

			$ nixos-rebuild --option substituters "<nowiki>http://binarycache.example.com</nowiki>" --option trusted-public-keys "binarycache.example.com-1:dsafdafDFW123fdasfa123124FADSAD" switch
			To do an offline install (providing your binary cache contains all the packages required);
			$ nixos-install --option substituters "<nowiki>http://binarycache.example.com</nowiki>" --option trusted-public-keys "binarycache.example.com-1:dsafdafDFW123fdasfa123124FADSAD"

	== See also ==		== See also ==

	<references group="cf."/>		<references group="cf."/>