FlakeHub Cache docs #17
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| .direnv/ | ||
| pnpm-lock.yaml | ||
| **/*.mdx | ||
| .next/ | ||
| .vscode/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| const SignupForm = () => { | ||
| return ( | ||
| <div | ||
| className="not-prose my-6 rounded-lg border-2 border-ds-magenta bg-gray-900 p-4 md:p-5 lg:p-6" | ||
| id="signup" | ||
| > | ||
| <div className="space-y-4 md:space-y-6"> | ||
| <p className="text-ds-white text-xl font-semibold"> | ||
| Register for the FlakeHub Cache private beta | ||
| </p> | ||
|
|
||
| <form | ||
| action="https://systems.us21.list-manage.com/subscribe/post?u=219191dcbd71bd0a5da006aed&id=da3f9b6422&f_id=00a5e7e1f0" | ||
| method="POST" | ||
| className="relative flex" | ||
| x-ph-capture-trigger="submit" | ||
| x-ph-capture-event="subscribe-private-beta" | ||
| > | ||
| <input type="hidden" name="FHBETA" value="yes" /> | ||
|
|
||
| <div className="flex flex-col gap-4 md:flex-row md:gap-0"> | ||
| <div className="flex border border-ds-violet"> | ||
| <input | ||
| placeholder="Email address" | ||
| type="email" | ||
| name="EMAIL" | ||
| className="placeholder-font-semibold focus:bg-ds-white bg-transparent px-4 py-2 placeholder-white focus:text-ds-sky-blue md:px-5 md:py-3" | ||
| /> | ||
| </div> | ||
| <div className="self-star flex md:border md:border-ds-violet"> | ||
| <button | ||
| type="submit" | ||
| className="duration-hover bg-ds-violet px-4 py-2 text-center font-extrabold transition-colors hover:text-ds-gray-lightest md:px-5 md:py-3" | ||
| > | ||
| Register | ||
| </button> | ||
| </div> | ||
| </div> | ||
| </form> | ||
| </div> | ||
| </div> | ||
| ); | ||
| }; | ||
|
|
||
| export default SignupForm; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| # FlakeHub Cache | ||
|
|
||
| *FlakeHub Cache* is a [Nix binary cache][cache] that works in conjunction with [FlakeHub][home]. | ||
| It has two main features that distinguish it from other Nix caching services: | ||
|
|
||
| 1. It enables you to [control access](#access-control) at the [flake][flakes] level. | ||
| 1. It uses a flexible and convenient [authentication](#authentication) model that doesn't require juggling access keys. | ||
|
|
||
| FlakeHub Cache is currently in **private beta** but you can sign up for the beta here and we'll add you as soon as we're ready: | ||
|
|
||
| <SignupForm /> | ||
|
|
||
| ## Access control | ||
|
|
||
| Nix caching solutions based on [nix-serve] serve an entire [Nix store][store] as a single monolithic cache and make all store paths in that cache available to anyone with a public key. | ||
| With FlakeHub Cache, on the contrary, you can grant or deny read access to specific users **at the [flake][flakes] level**, which affords substantially more granular access control. | ||
|
|
||
| Let's say that you're an admin for the org `omnicorp`. | ||
| You could manage access to your org's flakes in such a way that, for example: | ||
|
|
||
| * Only some trusted users would be allowed to pull store paths associated with the flake `super-duper-secure`. | ||
| * Anyone in your org can pull store paths associated with the `dev-environments` flake. | ||
|
|
||
| ## Authentication model | ||
|
|
||
| FlakeHub Cache authentication is based on [JSON Web Tokens][jwt] (JWTs or "jots"). | ||
| We currently use [GitHub] as our JWT authentication provider but will be adding support for [GitLab] in the near future. | ||
lucperkins marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Down the road, the flexibility of JWTs will enable us to support a wide range of additional authentication solutions, including [SAML] and [Single sign-on][sso] (SSO) providers. | ||
|
|
||
| In contrast, existing Nix caching services use static tokens for authentication. | ||
| This model places all of the operational burden of authentication on users; with FlakeHub Cache, however, we've opted to shift that burden to trusted authentication providers. | ||
|
|
||
| ## Pushing to the cache | ||
|
|
||
| FlakeHub Cache differs from existing Nix caching solutions because it forbids pushing to the cache in an ad-hoc way. | ||
| Thus, you can't push to the cache from your laptop or from one of your servers. | ||
| Instead, only *trusted builders* are allowed to push to the cache. | ||
| At the moment, this includes only [GitHub Actions runners][actions] but other options will be available in the future. | ||
|
|
||
| In order to push to FlakeHub Cache from GitHub Actions, your GitHub organization needs to be [registered for the beta](#signup). | ||
| Once you've been added—you'll be notified via email—you can configure your org's GitHub Actions workflows to use the cache. | ||
| Here's an example: | ||
|
|
||
| ```yaml {4-6,9-10} showLineNumbers filename=".github/workflows/nix.yml" | ||
| jobs: | ||
| build-nix-package: | ||
| runs-on: ubuntu-22.04 | ||
| permissions: | ||
| contents: read | ||
| id-token: write | ||
| steps: | ||
| - uses: actions/checkout@v3 | ||
| - uses: DeterminateSystems/nix-installer-action@main | ||
| - uses: DeterminateSystems/magic-nix-cache-action@main | ||
| # Build default package | ||
| - run: nix build | ||
| ``` | ||
|
|
||
| In this configuration: | ||
|
|
||
| * The `permissions` section enables you to authenticate to FlakeHub Cache. | ||
| No other authentication method, like public keys, is necessary. | ||
| * The [Magic Nix Cache Action][mnca] sets up authentication for FlakeHub Cache. | ||
|
|
||
| <Callout type="info"> | ||
|
There was a problem hiding this comment. Not clear how this callout relates to the stuff above it. Probably we want to say something like "You can push your stuff to the cache using one of the following actions: |
||
| You can push all of your flake outputs to FlakeHub Cache in [GitHub Actions][actions] using the [Determinate CI Action][ci]: | ||
|
|
||
| ```yaml filename=".github/workflows/ci.yml" | ||
| jobs: | ||
| DeterminateCI: | ||
| uses: DeterminateSystems/ci/.github/workflows/workflow.yml@main | ||
| permissions: | ||
| id-token: "write" | ||
| contents: "read" | ||
| ``` | ||
|
|
||
| This Action automatically: | ||
|
|
||
| * Discovers all Nix derivation outputs—`packages`, `devShells`, and more—on all architectures your flake supports using [Flake Schemas][schemas]. | ||
| * Builds all derivation outputs on appropriate Actions runners and uses the [Magic Nix Cache][mnca] to push to FlakeHub Cache. | ||
| * Publishes your flake releases to FlakeHub. | ||
| </Callout> | ||
|
|
||
| ## Pulling from the cache | ||
|
|
||
| In order to pull from the cache, you need to be properly authenticated in one of two ways: | ||
|
|
||
| 1. On GitHub Actions runners, authentication happens automatically. | ||
| 1. As an ordinary user on a laptop or workstation, you need to authenticate using [`fh login`][fh-login]. | ||
|
|
||
| <SignupForm /> | ||
|
|
||
| [actions]: https://docs.github.com/actions | ||
| [cache]: https://zero-to-nix.com/concepts/caching | ||
| [ci]: https://github.com/DeterminateSystems/ci | ||
| [determinate]: https://github.com/determinateSystems/determinate | ||
| [fh-login]: https://github.com/determinateSystems/fh?tab=readme-ov-file#log-into-flakehub | ||
| [flakes]: https://zero-to-nix.com/concepts/flakes | ||
| [github]: https://github.com | ||
| [gitlab]: https://gitlab.com | ||
| [home]: / | ||
| [jwt]: https://jwt.io | ||
| [login]: /login | ||
| [mnca]: https://github.com/determinateSystems/magic-nix-cache-action | ||
| [nix-serve]: https://nixos.org/manual/nix/stable/package-management/binary-cache-substituter | ||
| [saml]: https://en.wikipedia.org/wiki/SAML_2.0 | ||
| [schemas]: https://github.com/DeterminateSystems/flake-schemas | ||
| [sso]: https://en.wikipedia.org/wiki/Single_sign-on | ||
| [store]: https://zero-to-nix.com/concepts/store | ||
| [wizard]: https://flakehub.com/up | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IIRC the access control is at the repository level. If you have one flake per repo that's the same thing, but you could be releasing multiple flakes from the same repo, and they would share the same cache by default.