[go: up one dir, main page]

Determinate Nix

Determinate Nix

Determinate Nix is Determinate Systems’ validated and secure downstream distribution of NixOS/nix designed for enterprise use cases.

As a downstream distribution, Determinate Nix is fully compatible with and includes everything in upstream Nix but also features substantial upgrades like parallel evaluation, lazy trees, and a native Linux builder for macOS, making Nix workflows faster, CI/CD runs smoother, and the overall experience seamless across all environments. Every Determinate Nix release is validated on SOC 2 Type II infrastructure and backed by a defined Common Vulnerabilities and Exposures (CVE) process, providing the security, scale, and stability that organizations need across developer workstations, CI/CD, and the cloud.

Determinate Nix has two core components:

  • Our downstream distribution of the Nix CLI.
  • Determinate Nixd, a daemon that makes your experience of installing and using Nix dramatically more smooth.

Getting started

You can get started by installing Determinate Nix on your preferred platform:

Get Determinate for macOS

Configuring Determinate Nix

Determinate Nix generally handles configuration for you, and one of its core virtues is that it enables you to confidently use Nix while making fewer decisions about it—including configuration decisions. When you install Determinate Nix, the installer writes a nix.conf configuration file to /etc/nix/nix.conf with carefully chosen values.

If you need to provide custom configuration beyond this, however, you can write that additional configuration to /etc/nix/nix.custom.conf.

⚠️

It’s important that you not change the values generated by Determinate Nix in /etc/nix/nix.conf. If you do need to supply custom configuration, nix.custom.conf is the only supported way to do so in Determinate Nix.

Special features

Determinate Nix has a variety of features not currently available in upstream, including parallel evaluation, lazy trees, and a native Linux builder for macOS.

Parallel evaluation

Available since Determinate Nix 3.11.

Historically, Nix has been a single-threaded tool front to back. Determinate Nix has begun to change that with the introduction of parallel evaluation, which distributes work across multiple processors.

Parallelization can cut evaluation time in half for some Nix operations—especially the more computationally intensive ones—and promises to quietly make Nix faster and more efficient. We’ve begun with operations like nix search, nix flake check, nix flake show, and nix eval --json, but we intend to steadily expand coverage over time.

This feature also includes a new builtins.parallel function that you can use to speed up some complex Nix expressions, for example those involving import-from-derivation (IFD).

Parallel evaluation of Nix expressions is currently in developer preview and we will gradually roll it out to Determinate Nix users over the coming weeks and months. If you’re eager to try it out now, you can enable it on your system by adding this to your nix.custom.conf file:

eval-cores = 2

Set eval-cores to 0 to have Determinate Nix parallelize work across every core, or 1 to disable parallel evaluation.

If you’re an administrator and would like to opt in or out of parallel evaluation on an organization-wide basis, contact us at support@determinate.systems.

Lazy trees

Available since Determinate Nix 3.5.2.

Lazy trees provide faster and less resource-intensive evaluation in many standard flake usage scenarios. With lazy trees enabled, Nix scopes file copying to what the specific expression demands—and nothing more. More specifically, Nix uses a virtual filesystem to gather the necessary file state prior to copying anything to the Nix store, “mounting” lazy source inputs to this virtual filesystem at /nix/store/<random-hash>. This much more parsimonious mode of operation quietly makes just about everything in Nix faster, from standard package builds to development environments to NixOS deployment and beyond.

Lazy trees make an especially large performance impact in large repositories, including massive monorepos. For evaluations inside of the Nixpkgs repo, for example, we’ve frequently seen reductions in wall time of 3x or more and reductions in disk usage of 20x or more—and occasionally reductions far beyond even this.

Lazy trees are currently stable in Determinate Nix and enabled by default for all users.

You can disable lazy trees for a single operation—perhaps for testing performance differences with the feature enabled and disabled—by applying the --no-lazy-trees flag:

Disable lazy trees for a single operation
nix build --no-lazy-trees .#my-package

Although we don’t recommend it, you can disable lazy trees on your system by adding this to your nix.custom.conf file:

lazy-trees = false

If you’re an administrator and would like to disable lazy trees on an organization-wide basis, contact us at support@determinate.systems.

Native Linux builder

Available since Determinate Nix 3.8.4.

If you’re a macOS user, Determinate Nix offers a native Linux builder that you can use to build Docker images, NixOS systems, Linux packages, and other Linux-targeted derivations on macOS with no extra setup or configuration. To provide this cross-system capability, Determinate Nix uses macOS’s built-in Virtualization framework.

This feature will gradually be rolled out to Determinate Nix users over the coming weeks and months. If you’re eager to try it out now, contact us at support@determinate.systems to request access and include your FlakeHub user name.

Once you have access to the feature, builds like this will work without, for example, setting up a remote builder or running a local Docker image:

Build ARM Linux package on macOS
nix build nixpkgs#legacyPackages.aarch64-linux.ponysay

And because the native Linux builder targets both ARM Linux and x86 Linux, builds like this become possible as well:

Build x86 Linux package on macOS
nix build nixpkgs#legacyPackages.x86_64-linux.ponysay

Determinate Nixd

Determinate Nixd is a daemon for both Linux and macOS that makes your experience of installing and using Nix dramatically more smooth.

Determinate Nixd comes bundled with Determinate and doesn’t require any special setup beyond what’s covered in Getting started.

Enterprise certificate management (macOS)

Nix relies on TLS certificates to function. On macOS, Determinate Nixd automatically handles enterprise certificates.

On startup, the system’s Keychain certificates are exported for Nix. If the certificate store changes, you need to restart Determinate Nixd.

Managed garbage collection

Determinate Nixd automatically schedules and manages garbage collection for Nix, striving to:

  • Retain at least 30GB of disk space free to allow for system updates
  • Operate in a steady-state mode with between 5-20% disk space free

If your disk falls below 5% free, Determinate Nixd enters an “urgent” garbage collection mode to immediately free disk space.

Commands

Although Determinate Nixd is mostly meant to run in the background, it also enables you to perform some helpful tasks.

Log in to FlakeHub

To log in to FlakeHub using Determinate Nixd:

Log in to FlakeHub using Determinate Nixd
determinate-nixd login

By default, this logs in to FlakeHub using token authentication (the determinate-nixd login token command is equivalent). You need to generate a token in the FlakeHub UI to log in this way.

Determinate Nixd also enables you use federated authentication based on OpenID Connect (OIDC) and JSON Web Tokens (JWTs) to log in to FlakeHub from a variety of platforms:

Log in via Amazon STS

To log in via Amazon STS:

Log in to FlakeHub on AWS
determinate-nixd login aws
Log in on GitHub Actions

To log in on GitHub Actions:

Log in to FlakeHub on GitHub Actions
determinate-nixd login github-actions
Log in on GitLab CI/CD

To log in on GitLab CI/CD:

Log in to FlakeHub on GitLab CI/CD
determinate-nixd login gitlab-pipeline \
  --jwt-env-var FLAKEHUB_GITLAB_CI_TOKEN

The --jwt-env-var option enables you to specify the environment variable name that you’ve chosen for your GitLab-supplied JSON Web Token (make sure not to prefix the name with a $ as you may be used to doing). The example above would work for an authentication configuration like this:

job_logging_in_to_flakehub:
  id_tokens:
    FLAKEHUB_GITLAB_CI_TOKEN:
      aud: https://my-audience.dev

Check your login status

To show your current FlakeHub login status:

Display current authentication status
determinate-nixd status

This displays:

  • Whether you’re currently logged in
  • The FlakeHub user name under which you’re logged in
  • The FlakeHub organizations to which you are attached

Logout

Logout of current session
determinate-nixd auth logout

Bind your installation

Determinate Nixd allows users or system administrators to bind their installation to a specific FlakeHub customer.

Once this is done, future logins are validated against this binding — the user or one of the user’s organization must match the bound customer name.

Bind Determinate Nixd installation
determinate-nixd auth bind my-organization

Once an installation has been bound, only root or an elevated admin may undo the binding.

Reset Determinate Nixd binding and authentication
sudo determinate-nixd auth reset

Upgrade Nix

To upgrade Nix to the most recent version of Nix advised by Determinate Systems:

Upgrade to the most recent version of Determinate Nix
sudo determinate-nixd upgrade

Additionally, you may specify a target version to be installed:

Upgrade to a specific version of Determinate Nix
sudo determinate-nixd upgrade --version v3.6.2

You need to run this command with sudo, as in the example above.

At any time, you can run a version check to see if you need to upgrade.

Check your version

You can check which version of Determinate Nix you’re running using the version command:

Check which version of Determinate Nix you're running
determinate-nixd version

If you’re not on the latest version, Determinate Nixd provides upgrade instructions.

Initialize

To initialize Determinate Nix after system boot:

Initialize Determinate Nix after system boot
determinate-nixd init

To continue running the init command in perpetuity to keep the Nix store mounted:

Keep the Nix store mounted
determinate-nixd init \
  --keep-mounted

File a bug report

To file a bug report for Determinate:

File a bug report
determinate-nixd bug "Some bug title"

Optionally, you can supply a longer description as the second argument:

Supply a description when filing a bug report
determinate-nixd bug "Some bug title" "Some longer description"

You can the --advisory flag to indicate that the bug is meant only as an advisory rather than as a critical:

Label a bug report as an advisory
determinate-nixd bug "Some bug title" "Some longer description" \
  --advisory

You can also attach specific files to the report using the --attach option:

Attach files to a bug report
determinate-nixd bug "Some bug title" "Some longer description" \
  --attach ./flake.nix

Shell auto-completion

You can generate auto-completion scripts for various shells using the determinate-nixd completion command. Here’s an example:

Load auto-completion scripts for zsh
eval "$(determinate-nixd completion zsh)"

Scripts are available for these shells:

  • bash
  • elvish
  • fish
  • powershell
  • zsh

Configuring Determinate Nixd

You can modify the behavior of Determinate Nixd using the JSON configuration file located at /etc/determinate/config.json by default.

These parameters are available:

ParameterDescriptionOptions
garbageCollector.strategyThe garbage collection strategy used by Determinate Nixdautomatic (Determinate Nixd automatically collects garbage in the background)

disabled (no automatic garbage collection)
authentication.additionalNetrcSourcesA list of paths to netrc files that are combined by Determinate Nixd and used by Nix. These files must exist and not be in /nix/store or the daemon refuses to start.List of paths to files

Here’s an example configuration file:

/etc/determinate/config.json
{
  "garbageCollector": {
    "strategy": "automatic"
  },
  "authentication": {
    "additionalNetrcSources": [
      "/etc/determinate/netrc.custom"
    ]
  }
}

additionalNetrcSources

This option enables you to specify additional netrc files for use by Nix. Determinate Nixd combines these into a single effective netrc file after some brief validation:

  • Each file must contain only unique netrc entries (no duplicates across any of the files)
  • Each file must be a valid netrc file
  • Each file must not be accessed through the Nix store

Put another way, you can’t have /nix/store/...-my-netrc as an entry even if that file is a symlink to another path outside of the Nix store.

⚠️

The netrc file created and managed by Determinate Nixd is world readable. This is currently required by Determinate Nix.

This configuration shows how you can use Nix to manage additionalNetrcSources:

{
  environment.etc."determinate/config.json".text = ''
    {
      "authentication": {
        "additionalNetrcSources": [
          "/etc/corporate-mdm/provisioned/standard-netrc"
        ]
      }
    }
  '';
}

Determinate Nix 3.0 Reference Manual

For in-depth information about Determinate Nix 3.0, consult our work-in-progress reference manual.

The version of the reference manual corresponds to the specific Nix version on which Determinate Nix is based. It’s lightly edited to adjust to our published best practices but it may still contain some outdated suggestions regarding best practices. You may find scattered references to, for example, Nix channels, nix-* commands, and installation, uninstallation, and bug reporting procedures that

Our primary maintained documentation is here at docs.determinate.systems. Please consider manual.determinate.systems to be a deep technical reference and not an authoritative source about Determinate-Systems-recommended best practices or approaches.