|
| 1 | +--- |
| 2 | +title: Catalog Store |
| 3 | +description: Create a Catalog Store for publishing your own Flox packages |
| 4 | +--- |
| 5 | + |
| 6 | +# Setting up a Catalog Store |
| 7 | + |
| 8 | +Publishing your own software to your organization's Flox Catalog requires some |
| 9 | +initial setup, but the process is relatively straightforward. Flox supports |
| 10 | +publishing packages to a Catalog Store, which can exist in an AWS S3 bucket |
| 11 | +or in any S3 compatible service, like [MinIO][minio-s3-compatible]{:target="\_blank"} |
| 12 | +or [Backblaze B2][backblaze-b2-cloud-storage]{:target="\_blank"}. (For the |
| 13 | +sake of simplicity, this guide focuses on S3, but there are other providers |
| 14 | +available if you prefer them to AWS.) |
| 15 | + |
| 16 | +In order to use an S3 bucket to store artifacts built with Flox, you will need |
| 17 | +to set ingress and egress URIs on the catalog using a utility published by Flox. |
| 18 | +Then, all you need to do to publish your software is to call `flox publish`, |
| 19 | +and Flox will take care of the rest. |
| 20 | + |
| 21 | +[minio-s3-compatible]: https://min.io/product/s3-compatibility |
| 22 | +[backblaze-b2-cloud-storage]: https://www.backblaze.com/cloud-storage |
| 23 | + |
| 24 | +## Configure an AWS S3 Bucket |
| 25 | + |
| 26 | +The first step in setting up your Catalog Store is creation and configuration of |
| 27 | +an AWS S3 Bucket. There are numerous ways to accomplish this, including the AWS |
| 28 | +Console, the AWS CLI, and Terraform (or another infrastructure-as-code tool), |
| 29 | +to name a few. These processes are well documented, but to get started, |
| 30 | +it's best to refer directly to AWS documentation. |
| 31 | + |
| 32 | +- [What is Amazon S3?][amazon-s3]{:target="\_blank"} |
| 33 | +- [AWS S3 CLI Reference][aws-cli-reference-s3]{:target="\_blank"} |
| 34 | +- [Amazon Simple Storage Service API Reference][aws-s3-api-reference]{:target="\_blank"} |
| 35 | + |
| 36 | +Once your S3 bucket is set up and configured with the access policies deemed |
| 37 | +necessary by your organization's internal policies, you're ready to proceed to |
| 38 | +the next step. Someone from Flox can help you if you run into trouble during |
| 39 | +the setup process. Simply reach out to your designated point of contact, |
| 40 | +and we'll work with you to get you up and running. |
| 41 | + |
| 42 | +[amazon-s3]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html |
| 43 | +[aws-cli-reference-s3]: https://docs.aws.amazon.com/cli/latest/reference/s3/ |
| 44 | +[aws-s3-api-reference]: https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html |
| 45 | + |
| 46 | +## Ensure the Nix Daemon Has Access to the S3 Bucket |
| 47 | + |
| 48 | +As you probably know by now, the underlying technology powering Flox is Nix. |
| 49 | +Accordingly, we need to take a couple steps to ensure that the Nix daemon |
| 50 | +has access to the S3 bucket you've just created. To do so, |
| 51 | +you have a couple of options: |
| 52 | + |
| 53 | +1. Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and, if applicable, |
| 54 | +`AWS_SESSION_TOKEN` as environment variables, both for Flox and for |
| 55 | +the daemon itself |
| 56 | +1. Use the `aws configure` command |
| 57 | +[as described in the CLI reference][aws-cli-configure-command]{:target="\_blank"} |
| 58 | +to set those same values, and ensure that the AWS profile and region match those |
| 59 | +configured for the S3 bucket |
| 60 | + |
| 61 | +If you follow the second set of steps, you can confirm that everything is set |
| 62 | +up correctly by inspecting the values stored in `$HOME/.aws/credentials`. |
| 63 | + |
| 64 | +[aws-cli-configure-command]: https://awscli.amazonaws.com/v2/documentation/api/latest/reference/configure/index.html#configure |
| 65 | + |
| 66 | +## Set Catalog Store Ingress and Egress URIs |
| 67 | + |
| 68 | +Once you have your S3 bucket configured, the next step is to set an ingress URI |
| 69 | +and egress URI for your Catalog Store. Flox provides a utility for you |
| 70 | +that does exactly what you need, within a Flox environment. To use this, |
| 71 | +you'll need to run the following command: |
| 72 | + |
| 73 | +```sh |
| 74 | +flox activate -r flox/flox-catalog-util |
| 75 | +``` |
| 76 | + |
| 77 | +When you run this command, you'll see the following output: |
| 78 | + |
| 79 | +```console |
| 80 | +✅ You are now using the environment 'flox/flox-catalog-util (remote)'. |
| 81 | +To stop using this environment, type 'exit' |
| 82 | +``` |
| 83 | + |
| 84 | +Within the active Flox environment, you can simply run the following command: |
| 85 | + |
| 86 | +```sh |
| 87 | +catalog-util store --catalog "<my-catalog-name>" set --store-config '{ "store-type": "nix-copy", "ingress_uri": "s3://<my-bucket>", "egress_uri": "s3://<my-bucket>" }' |
| 88 | +``` |
| 89 | + |
| 90 | +You'll note that it's possible to set the ingress and egress URIs to the same |
| 91 | +value, if you wish to do so. |
| 92 | + |
| 93 | +## Create and Set a Signing Key |
| 94 | + |
| 95 | +At this point, you should have an appropriately configured Catalog Store |
| 96 | +to which you can publish your own software via the `flox publish` command. |
| 97 | +The last thing you need to worry about is configuring a signing key |
| 98 | +for publishing packages. |
| 99 | + |
| 100 | +The first step in this process is generating a key. This example illustrates |
| 101 | +how you would do so for a key called "my-key": |
| 102 | + |
| 103 | +sh``` |
| 104 | +nix key generate-secret --key-name my-key > my-key.key |
| 105 | +nix key convert-secret-to-public < my-key.key |
| 106 | +``` |
| 107 | +Once you've generated the key, you can configure Flox to sign the packages |
| 108 | +you publish with that key: |
| 109 | +
|
| 110 | +```sh |
| 111 | +flox config --set publish.signing_key "</path/to/my-key.key" |
| 112 | +``` |
| 113 | + |
| 114 | +Now you're ready to use Flox publish your own software to the Catalog Store |
| 115 | +that you just set up. |
0 commit comments