Skip to content

Setting up a Catalog Store

This is a Flox for Teams feature

This is a paid feature included with Flox for Teams.

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 can exist in an AWS S3 bucket or in any S3 compatible service, like MinIO or Backblaze B2. (For the sake of simplicity, this guide focuses on S3, but there are other providers available if you prefer them to AWS.)

In order to use an S3 bucket to store artifacts 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. Someone from 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.

Policy example

By default, S3 buckets are normally confined to be read by the bucket owner or users within the same AWS account. This is likely a decent starting point for the Catalog Store. However, if you'd like to make your published Flox software available to a wider audience, you can use the following policy as a starting point. Note this will make the contents of the bucket public, so be sure to understand the implications of this before applying it.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPublicRead",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::$BUCKET_NAME/*"
    }
  ]
}

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, we need to get AWS credentials, specifically AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and, if applicable, AWS_SESSION_TOKEN. Use the aws configure or aws configure sso command as described in the CLI reference to set those same values, and ensure that the AWS profile and region match those configured for the S3 bucket.

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

This step is accomplished as part of your organizational onboarding to Flox for Teams Early Access. Utilities for proper adminstration and self-service are coming soon.

Create and set a signing key

At this point, you should have an appropriately configured Catalog Store to which you can publish your own software via the flox publish command. In order for users to upload artifacts to the Catalog Store and then install those artifacts, you must configure public and private signing keys.

The private key is used to sign artifacts before uploading them, whereas the public key must be distributed to anyone you wish to be able to install those published artifacts. See the signing keys Cookbook page for instructions on configuring your signing keys.