Skip to content

start-here.md

Latest commit

 

History

History
125 lines (84 loc) · 4.95 KB

start-here.md

File metadata and controls

125 lines (84 loc) · 4.95 KB
Raw

Uninstall Previous Nix Installation (if applicable)

If you previously installed Nix using the Determinate Systems installer, you'll need to uninstall it first:

sudo /nix/nix-installer uninstall

If you installed Nix using a different method, follow the appropriate uninstall procedure for that installation method before proceeding.

Update Existing Official Nix Installation

If you already have the official Nix installer (not Determinate Systems) installed, you can simply update your configuration instead of reinstalling:

Step 1: Edit /etc/nix/nix.conf

Extend the following configuration in /etc/nix/nix.conf:

experimental-features = nix-command flakes
extra-substituters = https://nix-postgres-artifacts.s3.amazonaws.com
extra-trusted-public-keys = nix-postgres-artifacts:dGZlQOvKcNEjvT7QEAJbcV6b6uk7VF/hWMjhYleiaLI=

Caution

DO NOT add anyone to trusted-users in /etc/nix/nix.conf as it grants root without password. Instead, add the binary cache to extra-substituters and extra-trusted-public-keys.

Read about the binary cache in /nix/docs/binary-cache.md.

Step 2: Restart the Nix Daemon

After updating the configuration, restart the Nix daemon:

On macOS:

sudo launchctl stop org.nixos.nix-daemon
sudo launchctl start org.nixos.nix-daemon

On Linux (systemd):

sudo systemctl restart nix-daemon

Your Nix installation is now configured with the proper build caches and should work without substituter errors.

Install Nix (Fresh Installation)

We'll use the official Nix installer (see also nix.dev) with a custom configuration that includes our build caches and settings. This works on many platforms, including aarch64 Linux, x86_64 Linux, and macOS.

Step 1: Create nix.conf

First, create a file named nix.conf.extra with the following content:

experimental-features = nix-command flakes
extra-substituters = https://nix-postgres-artifacts.s3.amazonaws.com
extra-trusted-public-keys = nix-postgres-artifacts:dGZlQOvKcNEjvT7QEAJbcV6b6uk7VF/hWMjhYleiaLI=

Caution

DO NOT add anyone to trusted-users in /etc/nix/nix.conf as it grants root without password. Instead, add the binary cache to extra-substituters and extra-trusted-public-keys.

Read about the binary cache in /nix/docs/binary-cache.md.

Step 2: Install Nix

Run the following command to install the Nix version used in CI (pinned in .github/actions/install-nix/setup-nix.sh) with the custom configuration:

curl -fsSL https://releases.nixos.org/nix/nix-2.35.3/install -o nix-install
echo "69d0fe8fba8fe88f94c98b09964691ac9950abc7ecbf2ba861dc0533cfd901e9  nix-install" | sha256sum -c -
sh nix-install --daemon --yes --nix-extra-conf-file ./nix.conf

The checksum check makes sure the installer script is the one we pinned. On macOS, use shasum -a 256 -c - instead of sha256sum -c -.

This will install Nix with our build caches pre-configured, which should eliminate substituter-related errors.

After you do this, you must log in and log back out of your desktop environment (or restart your terminal session) to get a new login session. This is so that your shell can have the Nix tools installed on $PATH and so that your user shell can see the extra settings.

You should now be able to do something like the following; try running these same commands on your machine. Your versions are likely different from the ones shown:

$ nix --version
nix (Nix) 2.34.6

$ nix run nixpkgs#nix-info -- -m
 - system: `"x86_64-linux"`
 - host os: `Linux 5.15.90.1-microsoft-standard-WSL2, Ubuntu, 22.04.2 LTS (Jammy Jellyfish), nobuild`
 - multi-user?: `yes`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.34.6`
 - channels(root): `"nixpkgs"`
 - nixpkgs: `/nix/var/nix/profiles/per-user/root/channels/nixpkgs`

If that worked, you're ready to build.

Take Nix for a spin

Nix gives you current versions of many tools on any Linux distribution or macOS, and you need very little Nix knowledge to try it. nix run fetches a tool and runs it once. Nothing stays on your $PATH.

  • Q: Want the latest Deno?
  • A: nix run nixpkgs#deno -- --version
  • Q: A nice Python application like HTTPie?
  • A: nix run nixpkgs#httpie -- --version
  • Q: Favorite Rust tools like ripgrep and bat?
  • A: nix run nixpkgs#ripgrep -- --version and nix run nixpkgs#bat -- --version. fd, hyperfine, and eza are there too.

Note: nix profile installs the binaries so you do not need to nix run them each time, however this is not recommended. If curious about its use please consult your nearest nix mentor/advanced user.

To learn more about Nix, see Zero to Nix.