Skip to content

Cache Developer Information

Jump to bottom
SirBerg edited this page Apr 18, 2026 · 13 revisions

Setup

To start developing, clone the repo and run bun install:

git clone https://iglu-sh/iglu
bun install

For developing, we are usually using the sqlite db option, this means your config.toml should include the following:

[database]
database_type = 'sqlite'
database_file_location = './location_of/file.sqlite'

now run migrations:

bun run cache::migrations

All setup now, you should be good to start developing. For more documentation refer to this page.

General Dev Information

The Cache is written in Typescript using Express.js, our Linter is Biome.js The files live in /cache

The project structure is as follows:

  • routes: All Routes served by Express.js
  • helpers: Functions to be re-used exclusively inside the cache, all functions that could be re-used across other projects should be moved to /shared
  • cache-drizzle-conf: The Drizzle ORM Configurations
  • index.ts: The entrypoint into the cache
  • startup.ts: Actions performed at startup of the cache, thins such as initial tenant creations etc. get handled here

Api (routes) Structure

We follow these route structures:

  • routes/[tenant]: Every Route required for nix cache fetching, i.e every route the nix build processes use to fetch derivations live here
  • api/v1/cache: Every Route for Cachix uploads, any route in this directory follows the api standards set forward by the cachix team. These may not always be documented, so the responses and behaviours are documented later down in this document
  • api/v1/iglu: Every Route the Iglu Developers invent on their own, such as the upload endpoint for derivations and Rest-API routes for interacting with the cache programatically

Cachix

General Cachix information

We are developing a cachix-compliant cache, this means that we are aiming to make it possible that every user only needs to complete basic cachix setup to start using the cache (this also eliminates the need to develop a push-client).

Cachix Routes

The cachix client requires the following routes to be available on our cache:

  • api/v1/cache/[tenant]
  • api/v1/cache/[tenant]/key
  • api/v1/cache/[tenant]/multipart-nar
  • api/v1/cache/[tenant]/narinfo
  • api/v1/cache/[tenant]/multipart-nar/[uid]
  • api/v1/cache/[tenant]/multipart-nar/[uid]/complete

All of these routes need to be responsing correctly. The flow in which the cachix client hits these routes is as follows:

  1. api/v1/cache/[tenant] - This fetches the basic cache information that the cachix client needs for uploading
  2. api/v1/cache/[tenant]/narinfo - The cachix client asks the server which of the derivations it wants to push the server already has, the server responds with an array of nix store hashes that the server needs from the client
  3. api/v1/cache/[tenant]/multipart-nar - The cachix client hits this endpoint for every part it wants to upload, the server responds with an upload ID that the client has to provide in order to upload the derivation it wants
  4. api/v1/cache/[tenant]/multipart-nar/[uid] - The cachix client provides the server with the Md5 hash of the part it wants to upload, the server responds with an URL that the cachix client should push to
  5. api/v1/iglu/upload/[tenant]/[uid] - The cachix client pushes the raw binary to the server, the server responds 200 once it has successfully stored the binary
  6. api/v1/cache/[tenant]/multipart-nar/[uid]/complete - Once all the parts are received by the server, the cachix client calls this URL to complete the transfer. It also provides the server with meta information about the derivation it just stored and a filehash

Clone this wiki locally