Skip to content

Setting up a Catalog Store

Publishing your own software to your organization's Flox Catalog requires some initial setup, but the process is relatively straightforward. Flox supports publishing packages to a Catalog Store, which will exist in an AWS S3 bucket that is managed by your organization. In order to use this bucket to store binaries built with Flox, you will need to set ingress and egress URIs on the catalog using a utility published by Flox. Then, all you need to do to publish your software is to call flox publish, and Flox will take care of the rest.

Configure an AWS S3 Bucket

The first step in setting up your Catalog Store is creation and configuration of an AWS S3 Bucket. There are numerous ways to accomplish this, including the AWS Console, the AWS CLI, and Terraform (or another infrastructure-as-code tool), to name a few. These processes are well documented, but to get started, it's best to refer directly to AWS documentation.

Once your S3 bucket is set up and configured with the access policies deemed necessary by your organization's internal policies, you're ready to proceed to the next step; however, Flox can help you if you run into trouble during the setup process. Simply reach out to your designated point of contact, and we'll work with you to get you up and running.

Ensure the nix daemon Has Access to the S3 Bucket

As you probably know by now, the underlying technology powering Flox is Nix. Accordingly, we need to take a couple steps to ensure that the nix daemon has access to the S3 bucket you've just created. To do so, you have a couple of options:

  1. Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and, if applicable, AWS_SESSION_TOKEN as environment variables
  2. Use the aws configure command as described in the CLI reference to set those same values

If you follow the second set of steps, you can confirm that everything is set up correctly by inspecting the values stored in $HOME/.aws/credentials.

Set Catalog Store Ingress and Egress URIs

Once you have your S3 bucket configured, the next step is to set an ingress URI and egress URI for your Catalog Store. Flox provides a utility for you that does exactly what you need, within a Flox environment. To use this, you'll need to run the following command:

flox activate -r flox/flox-catalog-util

When you run this command, you'll see the following output:

✅ You are now using the environment 'flox/flox-catalog-util (remote)'.
To stop using this environment, type 'exit'

Within the active Flox environment, you can simply run the following command:

catalog-util store --catalog "<my-catalog-name>" set --store-config '{ "store-type": "nix-copy", "ingress_uri": "s3://<my-bucket>", "egress_uri": "s3://<my-bucket>" }'

You'll note that it's possible to set the ingress and egress URIs to the same value, if you wish to do so.

Set Signing Key When Publishing Your Package

At this point, you should have an appropriately Catalog Store to which you can publish your own software via the flox publish command. The last thing you need to worry about is configuring a signing key for publishing packages:

flox config --set publish.signing_key "</path/to/signing-key>"

Now you're ready to use Flox publish your own software to the Catalog Store that you just set up.