Cache

Getting Started

To get started using the Iglu cache, go ahead and download the docker. Here's a sample docker compose made for the following config.toml:

---
services:
  iglu:
    image: ghcr.io/iglu-sh/iglu-cache:latest
    volumes:
      - /path/to/binarys:/tmp/iglu
      - /path/to/config.toml:/config/config.toml
    ports:
      - 80:80
    environment:
      - IGLU_CACHE_CONF=/config

  # Optional if you use postgres as database backend
  postgres:
    image: postgres:18
    volumes:
      - /path/to/db/files:/var/lib/postgresql
    environment:
      - POSTGRES_USER=iglu
      - POSTGRES_PASSWORD=iglu
      - POSTGRES_DB=iglu

You'll also need to configure your cache. This is done through a config.toml. For your reference here are all the config keys with all possible values:

[database]
database_type = 'postgres' # or 'sqlite'
database_file_location = './out.db' #Required if database_type is set to sqlite, should be a persistent file that you have on a volume or mount in your container
user = 'iglu'
password = 'iglu'
host = 'postgres'
port = 5432
database_name = 'iglu'

[server]
hostname = 'https://example.com' # The base url of your server
hashing_secret = 'something_secure' # A baseline for our hashing, set this to a secure, randomly generated string

[storage]
storage_type = 'fs' # At the moment we only support filesystem storage but in the future we are going to implement s3 as another storage backend
binary_storage_directory = '/tmp/iglu' # This is where the binaries are actually stored

[tenants]
create_tenants_from_config = true # Set this to false if you do not want your config to define tenants (your caches)

# You may set infinite amounts of caches here, just copy and paste it and use the [[tenants.definitions]] for your other caches as well
[[tenants.definitions]]
github_username = "unknown_user" # Set to your Github Username, as far as we can tell this field ist largely unused by cachix or the nix clients
is_public = true # Set to false do deny access from any IP, set to false to allow access from any IP. If you have set it to false you will need to manually allow requests through Access Rules
name = '<name_of_tenant>' # The name of your tenant. For example if you have set this to 'example' your cache url would be: '<cache_baseurl>/example' This value must be unique accross all tenants
preferred_compression_method = 'zstd' # or xz
priority = 1 # Defines in which order your caches will be hit, for reference cache.nixos.org has a priority of 40 which means anything lower than 40 would be hit before cache.nixos.org and anything above 40 would be hit after
api_key_id = 'generated' # Or an ID of an actual Api key. If set to generated you will get a generated api key back. THIS WILL ONLY BE DISPLAYED ONCE!

# Define your deployment keys here (the things you use with cachix deploy)
# You may define both activation or agent keys here (refer to the cachix documentation for more information on that)
# CAREFULL: You will only see the generated token once in the console! 
[deployments]
create_deployments_from_config = true
enable_deployments = true # If you do not require this feature at all you can disable it here
[[deployments.definitions]]
name = 'Some Agent' # This name can be unique but it does not have to be
type = 'agent' # or 'activate' for an activation token
expires_at = '-1' # a date in iso format (e.g 2026-05-02T14:30:00Z) or -1 for no expiry
tenant_name = 'default' # the tenant name you are adding this deployment to
[[deployments.definitions]]
name ='Some Activation'
type = 'activate'
expires_at = '-1'
tenant_name = 'default'

# Only change options in the logger if you know what you're doing. The default values should be fine for most people
[logger]
logging_format = 'pretty' # or 'json'
logging_prefix = 'cache' # any string you want
logging_prefix_color = 'magenta' # or one of the supported colors
log_level = 'debug' # or 'info' 'warn' 'error'

Deployments

As we are a cache that aims to provide a fully cachix compatible API, we've also implemented the cachix deploy features. For the best documentation on how all of the cachix deploy features work, you should probably go and checkout the cachix documentation, which is hosted here

Configuring deployments in iglu

Deployments require two kinds of secrets: Agent and Activation Tokens. Both of which can be configured through the config.toml:

[deployments]
create_deployments_from_config = true
enable_deployments = true # If you do not require this feature at all you can disable it here

The above code snippets only configures iglu to offer the deployments endpoints to your cachix client, it doesn't configure any of the tokens mentioned, to do that you'll have to define keys like this:

Warning

The token that you define here will only be shown once at the startup of your iglu cache. They WONT be shown again afterwards so take note of them

[[deployments.definitions]]
name = 'Some Agent' # This name can be unique but it does not have to be
type = 'agent' # or 'activate' for an activation token
expires_at = '-1' # a date in iso format (e.g 2026-05-02T14:30:00Z) or -1 for no expiry
tenant_name = 'default' # the tenant name you are adding this deployment to

For an initial setup, you can use the below as a starting point (it configures an agent key and an activation key and enables the deployments feature):

[deployments]
create_deployments_from_config = true
enable_deployments = true
[[deployments.definitions]]
name = 'Some agent token' # This name can be unique but it does not have to be
type = 'agent' # or 'activate' for an activation token
expires_at = '-1' # a date in iso format (e.g 2026-05-02T14:30:00Z) or -1 for no expiry
tenant_name = 'default' # the tenant name you are adding this deployment to
[[deployments.definitions]]
name ='Some Activation Token'
type = 'activate'
expires_at = '-1'
tenant_name = 'default'