Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tutorial

In this tutorial, you run a Celler server on your own machine, create a binary cache, push a store path to it, and pull it back. You don’t need NixOS, S3, or a database server: everything lives in a single directory.

You need:

This setup is for trying Celler out. To run Celler for real, follow Deploying to NixOS afterwards.

Get Celler

You use two terminals in this tutorial:

  • The server terminal runs the Celler server.
  • The client terminal is where you run all other commands.

Open both terminals, and in each one, start a shell that has celler, cellerd, and openssl:

$ nix shell github:celler-cache/celler nixpkgs#openssl

Start the Server

In the server terminal, create a directory for the server’s data:

$ mkdir celler-demo
$ cd celler-demo

Celler uses signed tokens (JWTs) to decide who may do what. Generate a key pair to sign them. The server only needs the public key; you keep the private key to create tokens:

$ openssl genrsa -out private-key.pem 4096
$ openssl rsa -in private-key.pem -pubout -out public-key.pem
writing RSA key

Create server.toml with the following content:

listen = "[::]:8080"

# Keep the database in a SQLite file in this directory.
[database]
url = "sqlite://server.db?mode=rwc"

# Store the cached files in the storage/ directory.
[storage]
type = "local"
path = "storage"

# Accept tokens signed with our private key.
[jwt]
rs256-public-key-file = "public-key.pem"

All options are described in the server configuration reference.

Start the server:

$ cellerd -f server.toml
Celler 0.1.0 (release)
Running migrations...
* Migrating NARs to chunks...
* Migrating NAR schema...
Starting API server...
Listening on [::]:8080...

Leave the server running. Use the client terminal for the rest of the tutorial.

Create a Cache

In the client terminal, go to the celler-demo directory, because it contains the private key. Then create a token for a user called alice. It allows her to create the cache hello, configure it, push to it, and pull from it:

$ cd celler-demo
$ celler admin make-token --signing-key private-key.pem --sub alice --validity '3 months' \
    --pull hello --push hello \
    --create-cache hello --configure-cache hello --configure-cache-retention hello
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...

Log in to the server with this token. local is the name the client uses to refer to this server:

$ celler login local http://localhost:8080 eyJ...
✍️ Configuring server "local"

Now create the cache:

$ celler cache create hello
✨ Created cache "hello" on "local"

Push to the Cache

Push the celler package itself to the cache:

$ celler push hello $(which celler)
⚙️ Pushing 1 paths to "hello" on "local" (0 already cached, 6 in upstream)...
✅ h6pjy7d28mj6wihhn4fz2kqx7x9wy4my-celler-0.1.0 (50.09 MiB, 21.54 MiB/s)

celler push uploads the store path together with everything it depends on (its closure). Here, it skipped six dependencies because they are already available from cache.nixos.org (“in upstream”). You can change this behavior per cache.

Pull from the Cache

Configure Nix to use the new cache:

$ celler use hello
Configuring Nix to use "hello" on "local":
+ Substituter: http://localhost:8080/hello
+ Trusted Public Key: hello:HE3fhNGlAymSg6uGGrMMZGC20Of10/p8aZClxFzJ4rE=
+ Access Token

This adds the cache, its public key, and your access token to ~/.config/nix/nix.conf and ~/.config/nix/netrc.

celler is already in your Nix store, so Nix would not download it again. To see the download happen, let Nix fetch it into a separate store in the nix-demo directory:

$ nix-store --store $PWD/nix-demo -r $(which celler)
copying path '/nix/store/h6pjy7d28mj6wihhn4fz2kqx7x9wy4my-celler-0.1.0' from 'http://localhost:8080/hello'...
warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/h6pjy7d28mj6wihhn4fz2kqx7x9wy4my-celler-0.1.0

The copying path ... from 'http://localhost:8080/hello' line shows that Nix downloaded it from your cache.

Note

To pull into your real /nix/store on a multi-user Nix installation, your user must be trusted by the Nix daemon, or the cache must be configured system-wide. See the User Guide.

Make the Cache Public

So far, only someone with a token can read from the cache:

$ curl http://localhost:8080/hello/nix-cache-info
{"code":401,"error":"Unauthorized","message":"Unauthorized."}

Make it public, so that anyone can pull from it without a token:

$ celler cache configure hello --public
✅ Configured "hello" on "local"

$ curl http://localhost:8080/hello/nix-cache-info
WantMassQuery: 1
StoreDir: /nix/store
Priority: 41

Pushing still requires a token with push permission.

Clean Up Old Paths

Without limits, a binary cache grows forever. You can set a retention period: store paths that nobody has pushed or pulled for that long are deleted by the garbage collector.

Set the retention period to one second, so we don’t have to wait:

$ celler cache configure hello --retention-period '1s'
✅ Configured "hello" on "local"

The server runs garbage collection every 12 hours. Instead of waiting, run it once by hand:

$ cellerd -f server.toml --mode garbage-collector-once

The store path is gone from the cache:

$ curl http://localhost:8080/hello/h6pjy7d28mj6wihhn4fz2kqx7x9wy4my.narinfo
{"code":404,"error":"NoSuchObject","message":"The requested object does not exist."}

Reset the retention period to the server default, which is to keep everything:

$ celler cache configure hello --reset-retention-period
✅ Configured "hello" on "local"

Clean Up

When you are done, stop the server with Ctrl+C in the server terminal. Then remove the celler-demo directory. Nix makes the files in nix-demo read-only, so make them writable first:

$ cd ..
$ chmod -R u+w celler-demo
$ rm -rf celler-demo

celler use changed your Nix configuration. Remove the http://localhost:8080/hello substituter and the hello:... key from ~/.config/nix/nix.conf. Otherwise Nix keeps trying to reach the stopped server.

If you do the tutorial again, the new cache gets a new signing key, but Nix may still remember the old one for a while. If Nix reports that a path is not signed by any of the keys in 'trusted-public-keys', delete ~/.cache/nix.

Summary

You have:

  1. Run a Celler server with local storage
  2. Created a token and a cache
  3. Pushed a store path and pulled it back with Nix
  4. Made the cache public
  5. Removed old paths with garbage collection

What’s Next