Deploying with resolve-only tokens

This guide will show you how to deploy a NixOS configuration published on FlakeHub. The NixOS configuration is for an EtherCalc instance and it’s an output of the DeterminateSystems/demo flake. After some initial setup, you’ll be enable to deploy this configuration with one command:

fh apply nixos DeterminateSystems/demo/0.1#nixosConfigurations.ethercalc-demo

Prerequisites

1. The target machine must already be running Determinate.
2. The target machine must have fh version 0.1.18 or newer.
3. Your user must be an administrator of your FlakeHub organization.
4. Your FlakeHub organization must have a published flake with:
   • include-output-paths: true in the GitHub Action inputs and
   • a NixOS, nix-darwin, or Home Manager configuration, and that configuration must also be running Determinate for continued deployments.

Create a resolve-only token

Visit FlakeHub, log in, and navigate to your organization’s Device tokens tab. If you know your organization’s name already, you can reach that tab via the URL with this structure:

Otherwise, you can navigate manually:

1. Click on your face in the upper-right corner of the FlakeHub UI, then select Settings.
2. Click on Organizations.
3. Next to your organization, click Settings.
4. Select the Device tokens tab.

Once you’re in the tab, create a resolve-only token:

1. Click New Token.
2. Fill in a short description, like Deploy to raspberrypi-garage.
3. Select Resolve only for the token type
4. In the project menu, select the project you want to deploy. For this demo, for example, you’d select DeterminateSystems/demo.
5. In the field above the list of published versions, enter in the SemVer version requirement the clients will request. For this demo, 0.1. The versions below will indicate whether that version is allowed to be deployed. Note that the version requirement in the token form must exactly match the fh apply command used by the client.
6. Select the attribute path the machine can deploy. For the demo, select nixosConfigurations.ethercalc-demo.
7. Finally, click Create token and copy the created token.

Log the target machine in to FlakeHub

Log in to the target machine and log in to FlakeHub:

sudo determinate-nixd login token

Paste the just-created token, hit Enter, and you’ll see a confirmation like this:

Logged in: true
FlakeHub user name: DeterminateSystems
FlakeHub organizations: []

Execute your first deploy

Now that you’re logged in, run this fh apply command to perform the deploy:

sudo fh apply nixos DeterminateSystems/demo/0.1#nixosConfigurations.ethercalc-demo

fh apply nixos creates a short-lived token to access the cached closure of the NixOS configuration. The generated token is valid for one hour.

Next Steps

Continuous deployment

You can orchestrate the execution of the fh apply command across your fleet using tools like Amazon Systems Manager (SSM) or a systemd unit on a timer.

Precise roll-forward / roll-back semantics

The version number in DeterminateSystems/demo/0.1 is not a specific version but rather a SemVer version requirement. Specifically, 0.1 means any release with a major and minor version of 0.1.

This means that if you use a “loose” version like 0.1 you won’t be able to roll back using a previously run fh apply step because it ressolves to the newest release

Resolve-only tokens can pass one of two version requirements:

• The exact version requirement in the creation token process (0.1 in this case) or
• An exact version requirement that is acceptable by the original token’s requirement.

In other words, a resolve-only token can deploy with exactly the same version requirement…

sudo fh apply nixos DeterminateSystems/demo/0.1#nixosConfigurations.ethercalc-demo

…or an exact version within that requirement…

sudo fh apply nixos DeterminateSystems/demo/=0.1.175#nixosConfigurations.ethercalc-demo

…but not a similar but imprecise version requirement:

sudo fh apply nixos DeterminateSystems/demo/0.1.123#nixosConfigurations.ethercalc-demo

When integrating fh apply in a CI/CD pipeline, strive to pass an exact version requirement to fh apply. The exact version match is available from the flakeref_exact output of the flakehub-push GitHub Action.