Attic

https://github.com/zhaofengli/attic
Admin
Attic is a self-hostable Nix Binary Cache server with S3-compatible storage, featuring global...
Tokens:17,727
Snippets:114
Trust Score:9.3
License:Apache-2.0
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install and Run Attic Server

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This snippet shows how to install Attic using Nix and start the server in monolithic mode with local storage and a SQLite database. The server automatically configures a default path for its configuration file.

```bash
$ nix shell github:zhaofengli/attic
```

```console
$ atticd
Attic Server 0.1.0 (release)

-----------------
Welcome to Attic!

A simple setup using SQLite and local storage has been configured for you in:

    /home/zhaofeng/.config/attic/server.toml

Run the following command to log into this server:

    attic login local http://localhost:8080 eyJ...

Documentations and guides:

    https://docs.attic.rs

Enjoy!
-----------------

Running migrations...
* Migrating NARs to chunks...
* Migrating NAR schema...
Starting API server...
Listening on [::]:8080...
```

--------------------------------

### Create and Log into an Attic Cache

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This demonstrates logging into the Attic server using credentials obtained from the server output and then creating a new cache named 'hello'. It requires the server to be running and accessible.

```console
# Copy and paste from the atticd output
$ attic login local http://localhost:8080 eyJ...
✍️ Configuring server "local"

$ attic cache create hello
✨ Created cache "hello" on "local"
```

--------------------------------

### Attic CLI: Get Cache Information

Source: https://context7.com/zhaofengli/attic/llms.txt

Provides an example of retrieving detailed information about an Attic cache using `attic cache info`. The output includes the cache's name, public status, store directory, priority, public key, substituter endpoint, and API endpoint.

```bash
# Show cache info
attic cache info my-cache

# Output:
# Cache: my-cache
# Public: yes
# Store Directory: /nix/store
# Priority: 50
# Public Key: my-cache:abc123...
# Substituter Endpoint: https://cache.example.com/my-cache
# API Endpoint: https://cache.example.com/
```

--------------------------------

### Push Artifacts to Attic Cache

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This command pushes the Attic client executable itself to the 'hello' cache. It showcases Attic's ability to automatically skip already cached content from upstream sources like cache.nixos.org and highlights its global deduplication feature.

```bash
$ attic push hello $(which attic)
⚙️ Pushing 1 paths to "hello" on "local" (0 already cached, 45 in upstream)...
✅ r5d7217c0rjd5iiz1g2nhvd15frck9x2-attic-0.1.0 (52.89 MiB/s)
```

--------------------------------

### Download NAR Archive with cURL

Source: https://context7.com/zhaofengli/attic/llms.txt

Demonstrates how to download a NAR archive from a given URL using the cURL command-line tool. This is typically used for installing Nix packages from a binary cache. The example shows a basic download and mentions potential redirections to S3 or streaming for multi-chunk NARs.

```bash
# Download NAR
curl https://cache.example.com/my-cache/nar/abc123xyz.nar \
  -o path.nar

# Server may redirect to S3 for single-chunk NARs
# or stream multi-chunk reassembly
```

--------------------------------

### Configure Binary Cache Retention Period

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This command configures the retention period for a specific binary cache named 'hello'. Setting a short retention period like '1s' (1 second) is useful for testing garbage collection. The command outputs a confirmation message indicating the configuration has been applied to the 'local' setup.

```bash
$ attic cache configure hello --retention-period '1s'
✅ Configured "hello" on "local"
```

--------------------------------

### Configure Nix to Use Attic Cache and Pull Artifacts

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This section explains how to configure Nix to use a specific Attic cache ('hello') as a substituter. It then demonstrates pulling an artifact (the Attic executable) into a separate directory using `nix-store --store`, bypassing the main Nix store.

```bash
# Automatically configures ~/.config/nix/nix.conf for you
$ attic use hello
Configuring Nix to use "hello" on "local":
+ Substituter: http://localhost:8080/hello
+ Trusted Public Key: hello:vlsd7ZHIXNnKXEQShVnd7erE8zcuSKrBWRpV6zTibnA=
+ Access Token

$ nix-store --store $PWD/nix-demo -r $(which attic)
[snip]
copying path '/nix/store/r5d7217c0rjd5iiz1g2nhvd15frck9x2-attic-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/r5d7217c0rjd5iiz1g2nhvd15frck9x2-attic-0.1.0

$ ls nix-demo/nix/store/r5d7217c0rjd5iiz1g2nhvd15frck9x2-attic-0.1.0/bin/attic
nix-demo/nix/store/r5d7217c0rjd5iiz1g2nhvd15frck9x2-attic-0.1.0/bin/attic
```

--------------------------------

### Make an Attic Cache Public

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This command configures the 'hello' cache to be publicly accessible, allowing unauthenticated users to pull artifacts. It also shows how to query cache information using `curl` after making it public.

```bash
$ attic cache configure hello --public
✅ Configured "hello" on "local"

# Now we can query the cache without being authenticated
$ curl http://localhost:8080/hello/nix-cache-info
WantMassQuery: 1
StoreDir: /nix/store
Priority: 41
```

--------------------------------

### Log in to Attic Server

Source: https://github.com/zhaofengli/attic/blob/main/book/src/user-guide/README.md

Logs into an Attic server using the 'attic login' command. Requires the server name, URL, and an authentication token. This command configures the client to interact with the specified server.

```bash
attic login central https://attic.domain.tld/ eyJ...
```

--------------------------------

### Generate JWT Tokens for Access Control

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This snippet illustrates how to create JWT tokens with specific permissions using `atticadm`. The first token grants read and write access to the 'hello' cache, while the second token allows creating, pushing to, and pulling from caches prefixed with 'alice-*'.

```bash
$ atticadm make-token --sub alice --validity '3 months' --pull hello --push helloeyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6MTY4MDI5MzMzOSwiaHR0cHM6Ly9qd3QuYXR0aWMucnMvdjEiOnsiY2FjaGVzIjp7ImhlbGxvIjp7InIiOjEsInciOjF9fX19.XJsaVfjrX5l7p9z76836KXP6Vixn41QJUfxjiK7D-LM
```

```bash
$ atticadm make-token --sub alice --validity '3 months' --pull 'alice-*' --push 'alice-*' --create-cache 'alice-*'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6MTY4MDI5MzQyNSwiaHR0cHM6Ly9qd3QuYXR0aWMucnMvdjEiOnsiY2FjaGVzIjp7ImFsaWNlLSoiOnsiciI6MSwidyI6MSwiY2MiOjF9fX19.MkSnK6yGDWYUVnYiJF3tQgdTlqstfWlbziFWUr-lKUk
```

--------------------------------

### Attic CLI: Create New Cache

Source: https://context7.com/zhaofengli/attic/llms.txt

Demonstrates the creation of a new binary cache using `attic cache create`. Examples include creating a public cache with default settings and a cache with custom configurations such as store directory, priority, and upstream cache key.

```bash
# Create public cache with defaults
attic cache create my-cache

# Create with custom configuration
attic cache create team-cache \
  --public \
  --store-dir /nix/store \
  --priority 40 \
  --upstream-cache-key-name cache.nixos.org-1
```

--------------------------------

### Basic Server Setup (TOML)

Source: https://context7.com/zhaofengli/attic/llms.txt

Configuration file (`/etc/atticd/server.toml`) for setting up an Attic server. It specifies listening address, allowed hosts, API endpoint, PostgreSQL database connection URL, S3 storage details (region, bucket, endpoint, credentials), chunking parameters, compression settings, garbage collection interval, and JWT signing secret.

```toml
# /etc/atticd/server.toml

listen = "[::]:8080"
allowed-hosts = ["cache.example.com"]
api-endpoint = "https://cache.example.com/"

[database]
url = "postgresql://attic:password@localhost/attic"

[storage]
type = "s3"
region = "us-east-1"
bucket = "attic-nix-cache"
endpoint = "https://s3.amazonaws.com"

[storage.credentials]
access_key_id = "AKIAIOSFODNN7EXAMPLE"
secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

[chunking]
nar-size-threshold = 65536
min-size = 16384
avg-size = 65536
max-size = 262144

[compression]
type = "zstd"
level = 8

[garbage-collection]
interval = "12 hours"
default-retention-period = "0"

[jwt.signing]
token-hs256-secret-base64 = "base64encodedsecret..."

```

--------------------------------

### Get Attic Cache Information

Source: https://github.com/zhaofengli/attic/blob/main/book/src/user-guide/README.md

Retrieves details about a specific Attic cache, including its public key and binary cache endpoint. This information is useful for manual Nix configuration.

```console
$ attic cache info foo
               Public: true
           Public Key: foo:WcnO6s4aVkB6CKRaPPpKvHLZykWXASV6c+/Ssg8uQEY=
Binary Cache Endpoint: https://attic.domain.tld/foo
      Store Directory: /nix/store
             Priority: 41
  Upstream Cache Keys: ["cache.nixos.org-1"]
     Retention Period: Global Default
```

--------------------------------

### Display Binary Cache Information

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This command retrieves and displays detailed information about the 'hello' binary cache. The output includes its public status, public key, API endpoints, store directory, priority, and upstream cache configurations. Crucially, it shows that the Retention Period is now set to 'Global Default', indicating that the specific override has been removed.

```console
$ attic cache info hello
               Public: true
           Public Key: hello:vlsd7ZHIXNnKXEQShVnd7erE8zcuSKrBWRpV6zTibnA=
Binary Cache Endpoint: http://localhost:8080/hello
         API Endpoint: http://localhost:8080/
      Store Directory: /nix/store
             Priority: 41
  Upstream Cache Keys: ["cache.nixos.org-1"]
     Retention Period: Global Default
```

--------------------------------

### Attic Server Component Modes

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This section outlines different modes for running the Attic server components in a production environment. It highlights that while 'api-server' can be replicated, the 'garbage-collector' cannot. The 'api-server' is stateless, suitable for scaling, whereas the 'garbage-collector' is stateful and singular.

```text
- `api-server`: Stateless and can be replicated.
- `garbage-collector`: Performs periodic garbage collection. Cannot be replicated.
```

--------------------------------

### Query Nix Store via FFI in Rust

Source: https://context7.com/zhaofengli/attic/llms.txt

Interacts with the local Nix store using FFI to libnixstore. This example demonstrates connecting to the Nix daemon, resolving store paths, querying path information (NAR hash, size, references, signatures), and computing filesystem closures.

```rust
use attic::nix_store::{NixStore, StorePath};

#[tokio::main]
async fn main() -> attic::error::AtticResult<()> {
    // Connect to Nix daemon
    let store = NixStore::connect()?;

    // Resolve store path
    let path_str = "/nix/store/abc123xyz-hello-2.12";
    let store_path = store.follow_store_path(path_str).await?;

    // Query path info
    let path_info = store.query_path_info(&store_path).await?;
    println!("NAR hash: {}", path_info.nar_hash);
    println!("NAR size: {}", path_info.nar_size);
    println!("References: {:?}", path_info.references);
    println!("Signatures: {:?}", path_info.sigs);

    // Compute closure
    let roots = vec![store_path.clone()];
    let closure = store.compute_fs_closure_multi(
        &roots,
        false, // flip_direction
        false, // include_outputs
        false, // include_derivers
    ).await?;

    println!("Closure has {} paths", closure.len());
    for path in closure {
        println!("  - {}", path);
    }

    Ok(())
}

```

--------------------------------

### Enable Attic Cache for Nix

Source: https://github.com/zhaofengli/attic/blob/main/book/src/user-guide/README.md

Configures Nix to automatically use a specified Attic cache. This command adds the cache to Nix configuration, typically ~/.config/nix/nix.conf, and sets up necessary credentials.

```bash
attic use foo
```

--------------------------------

### GET /{cache_name}/{nar_hash}.narinfo

Source: https://context7.com/zhaofengli/attic/llms.txt

Download metadata about a store path in Nix's .narinfo format.

```APIDOC
## GET /{cache_name}/{nar_hash}.narinfo

### Description
Retrieves the .narinfo file for a specific store path within a cache.

### Method
GET

### Endpoint
/{cache_name}/{nar_hash}.narinfo

### Parameters
#### Path Parameters
- **cache_name** (string) - Required - The name of the cache.
- **nar_hash** (string) - Required - The hash of the NAR file for which to retrieve the .narinfo.
```

--------------------------------

### Push Store Path to Attic Cache

Source: https://github.com/zhaofengli/attic/blob/main/book/src/user-guide/README.md

Pushes a store path or a result from the current directory to a specified Attic cache. This command uploads build artifacts to the cache for sharing or backup.

```bash
attic push foo /nix/store/...
```

```bash
attic push foo ./result
```

```bash
attic push foo /run/current-system
```

--------------------------------

### Attic CLI: Push Store Paths

Source: https://context7.com/zhaofengli/attic/llms.txt

Details the `attic push` command for uploading Nix store paths to a cache. It covers pushing single or multiple paths, controlling parallelism (`-j`), disabling closure computation (`--no-closure`), pushing from stdin, ignoring upstream cache filters, and provides an example of the progress output.

```bash
# Push single path with closure
nix build .#hello
attic push my-cache ./result

# Push multiple paths
attic push my-cache ./result1 ./result2 ./result3

# Push with 10 parallel workers
attic push -j 10 my-cache ./result

# Push without computing closures (only the direct path)
attic push --no-closure my-cache ./result

# Push from stdin (useful in scripts)
nix-store -qR ./result | attic push --stdin my-cache

# Force upload even if signed by upstream caches
attic push --ignore-upstream-cache-filter my-cache ./result

# Output shows progress:
# ⚙️ Pushing 5 paths to "my-cache" on "my-server"...
# ✅ abc123-package-1.0 (29.69 MiB/s)
# 🕒 def456-package-2.0  ███████████  123.45 MiB (41.32 MiB/s)
```

--------------------------------

### GET /_api/v1/cache-config/{cache_name}

Source: https://context7.com/zhaofengli/attic/llms.txt

Retrieve cache metadata including public key and endpoint information.

```APIDOC
## GET /_api/v1/cache-config/{cache_name}

### Description
Retrieves the configuration details for a specific cache.

### Method
GET

### Endpoint
/_api/v1/cache-config/{cache_name}

### Parameters
#### Path Parameters
- **cache_name** (string) - Required - The name of the cache to retrieve configuration for.

### Response
#### Success Response (200)
- **substituter_endpoint** (string) - The URL for substituter access.
- **api_endpoint** (string) - The base URL for the API.
- **public_key** (string) - The public key associated with the cache.
- **priority** (integer) - The priority of the cache.
- **is_public** (boolean) - Whether the cache is publicly accessible.
- **store_dir** (string) - The Nix store directory path.
- **upstream_cache_key_names** (array of strings) - List of upstream cache key names.

#### Response Example
```json
{
  "substituter_endpoint": "https://cache.example.com/my-cache",
  "api_endpoint": "https://cache.example.com/",
  "public_key": "my-cache:abc123...",
  "priority": 50,
  "is_public": true,
  "store_dir": "/nix/store",
  "upstream_cache_key_names": ["cache.nixos.org-1"]
}
```
```

--------------------------------

### Retrieve Nix Cache Info with cURL

Source: https://context7.com/zhaofengli/attic/llms.txt

Shows how to fetch Nix cache metadata from a server using cURL. This information is crucial for configuring Nix to use the binary cache as a substituter. The example includes the expected response format, detailing `StoreDir`, `WantMassQuery`, and `Priority`.

```bash
# Get nix-cache-info
curl https://cache.example.com/my-cache/nix-cache-info

# Response
StoreDir: /nix/store
WantMassQuery: 1
Priority: 50
```

--------------------------------

### Configure Attic Client for Multi-Server Setup

Source: https://context7.com/zhaofengli/attic/llms.txt

This TOML configuration for the Attic client allows specifying multiple backend servers with different endpoints and authentication tokens or token files. It enables easy switching between servers, such as production, staging, and local development environments, by setting a default server.

```toml
# ~/.config/attic/config.toml

default-server = "production"

[servers.production]
endpoint = "https://cache.example.com/"
token = "eyJhbGciOiJIUzI1NiIs..."

[servers.staging]
endpoint = "https://staging-cache.example.com/"
token = "eyJhbGciOiJIUzI1NiIs..."

[servers.local]
endpoint = "http://localhost:8080/"
token-file = "/run/secrets/attic-local-token"

[servers.ci]
endpoint = "https://ci-cache.internal/"
token-file = "/var/lib/buildbot/attic-token"

```

--------------------------------

### Configure Nix Cache Declaratively (NixOS)

Source: https://github.com/zhaofengli/attic/blob/main/book/src/user-guide/README.md

Declaratively configures Nix to use an Attic cache on NixOS by setting substituters and trusted-public-keys in the system configuration. This ensures the cache is used across reboots.

```nix
{
  nix.settings = {
    substituters = [
      "https://attic.domain.tld/foo"
    ];
    trusted-public-keys = [
      "foo:WcnO6s4aVkB6CKRaPPpKvHLZykWXASV6c+/Ssg8uQEY="
    ];
  };
}
```

--------------------------------

### Generate Access Token with atticadm (Bash)

Source: https://context7.com/zhaofengli/attic/llms.txt

Creates JWT tokens using the `atticadm` command-line tool. This allows for fine-grained cache permissions for pull, push, and creating caches. The example shows generating a token for a user 'alice' with specific permissions.

```bash
# Generate token with atticadm
atticadm make-token \
  --sub "alice" \
  --validity "1 year" \
  --pull "public-*" \
  --push "personal-*" \
  --create-cache "team-*" \
  --configure-cache "team-*"

# Output: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Token contains these claims:
# {
#   "sub": "alice",
#   "exp": 1735689600,
#   "https://jwt.attic.rs/v1": {
#     "caches": {
#       "public-*": {
#         "r": 1
#       },
#       "personal-*": {
#         "r": 1,
#         "w": 1
#       },
#       "team-*": {
#         "r": 1,
#         "w": 1,
#         "cc": 1,
#         "cr": 1
#       }
#     }
#   }
# }

```

--------------------------------

### Verify Object Deletion After GC

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

These commands demonstrate the effect of garbage collection. The first attempts to retrieve a store path that should have been deleted, resulting in a 'don't know how to build these paths' error. The second attempts to fetch a NAR info file via HTTP, which returns a 404 NoSuchObject error, confirming the object no longer exists.

```console
$ nix-store --store $PWD/nix-demo-2 -r $(which attic)
don't know how to build these paths:
  /nix-store/v660wl07i1lcrrgpr1yspn2va5d1xgjr-attic-0.1.0
error: build of '/nix-store/v660wl07i1lcrrgpr1yspn2va5d1xgjr-attic-0.1.0' failed

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

--------------------------------

### Attic CLI: Watch Store for Changes

Source: https://context7.com/zhaofengli/attic/llms.txt

Explains the `attic watch-store` command, which monitors the Nix store for new builds and automatically pushes completed store paths to a specified cache. Options include controlling parallel workers (`-j`), disabling closure computation, and an example of the monitoring behavior.

```bash
# Watch Nix store and auto-push
attic watch-store my-cache

# Watch with 8 parallel workers
attic watch-store -j 8 my-cache

# Watch without computing closures
attic watch-store --no-closure my-cache

# The watcher monitors /nix/store for new .lock files
# and pushes paths when builds complete
# Operations are batched: 2s since last path or 10s total
```

--------------------------------

### Manually Trigger Garbage Collection

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This command manually initiates the garbage collection process for the Attic server. This is useful for immediately cleaning up unreferenced objects after configuring a short retention period or making changes. The command's execution leads to the removal of specified store paths.

```bash
atticd --mode garbage-collector-once
```

--------------------------------

### Get Cache Configuration using cURL

Source: https://context7.com/zhaofengli/attic/llms.txt

This cURL command retrieves the configuration details for a specific Attic cache. The response includes information such as the substituter endpoint, API endpoint, public key, and upstream cache references. This is essential for clients to correctly interact with the cache.

```bash
# Get cache config
curl https://cache.example.com/_api/v1/cache-config/my-cache \
  -H "Authorization: Bearer ${TOKEN}"

# Response
{
  "substituter_endpoint": "https://cache.example.com/my-cache",
  "api_endpoint": "https://cache.example.com/",
  "public_key": "my-cache:abc123...",
  "priority": 50,
  "is_public": true,
  "store_dir": "/nix/store",
  "upstream_cache_key_names": ["cache.nixos.org-1"]
}
```

--------------------------------

### Generate Admin Token with All Permissions (Bash)

Source: https://context7.com/zhaofengli/attic/llms.txt

Generates an administrative JWT token with full access permissions across all caches using `atticadm`. This includes pull, push, delete, create cache, configure cache, configure cache retention, and destroy cache permissions. The example demonstrates the command and lists the available permission flags.

```bash
# Admin token for all caches
atticadm make-token \
  --sub "admin" \
  --validity "2 years" \
  --pull "*" \
  --push "*" \
  --delete "*" \
  --create-cache "*" \
  --configure-cache "*" \
  --configure-cache-retention "*" \
  --destroy-cache "*"

# Permission flags:
# r  (pull): Download from cache
# w  (push): Upload to cache
# d  (delete): Delete objects
# cc (create_cache): Create the cache
# cr (configure_cache): Reconfigure cache
# cq (configure_cache_retention): Set retention/quota
# cd (destroy_cache): Delete cache

```

--------------------------------

### Stream NAR Archive from Nix Store Path in Rust

Source: https://context7.com/zhaofengli/attic/llms.txt

Streams the contents of a Nix store path as a NAR archive, suitable for uploading. This example also demonstrates computing the SHA256 hash of the NAR archive while streaming its content. It requires 'attic::nix_store', 'attic::hash', and 'tokio' crates.

```rust
use attic::nix_store::NixStore;
use attic::hash::Hash;
use tokio::io::AsyncReadExt;
use sha2::{Sha256, Digest};

#[tokio::main]
async fn main() -> attic::error::AtticResult<()> {
    let store = NixStore::connect()?;
    let store_path = store.follow_store_path(
        "/nix/store/abc123xyz-hello-2.12"
    ).await?;

    // Stream NAR archive
    let mut nar_stream = store.nar_from_path(&store_path).await?;

    // Compute hash while streaming
    let mut hasher = Sha256::new();
    let mut total_size = 0;
    let mut buffer = vec![0u8; 65536];

    loop {
        let n = nar_stream.read(&mut buffer).await?;
        if n == 0 {
            break;
        }

        hasher.update(&buffer[..n]);
        total_size += n;
    }

    let nar_hash = hasher.finalize();
    let nar_hash_str = format!("sha256:{}", hex::encode(nar_hash));

    println!("NAR hash: {}", nar_hash_str);
    println!("NAR size: {}", total_size);

    Ok(())
}

```

--------------------------------

### Reset Binary Cache Retention Period to Default

Source: https://github.com/zhaofengli/attic/blob/main/book/src/tutorial.md

This command resets the retention period for the 'hello' binary cache back to its global default setting. This action effectively disables the previously configured short retention period, preventing automatic deletion of objects based on that specific cache's setting. A confirmation message is displayed upon successful reset.

```console
$ attic cache configure hello --reset-retention-period
✅ Configured "hello" on "local"
```

--------------------------------

### Attic CLI: Login to Server

Source: https://context7.com/zhaofengli/attic/llms.txt

Illustrates how to log in to an Attic server using the `attic login` command. It covers basic login with endpoint and token, setting a server as default, and shows the resulting configuration file structure typically stored in `~/.config/attic/config.toml`.

```bash
# Login to server
attic login my-server https://cache.example.com/ eyJhbGc...

# Set as default server
attic login --set-default prod https://cache.example.com/ eyJhbGc...

# Configuration stored in ~/.config/attic/config.toml
# [servers.my-server]
# endpoint = "https://cache.example.com/"
# token = "eyJhbGc..."
```

--------------------------------

### POST /_api/v1/cache-config/{cache_name}

Source: https://context7.com/zhaofengli/attic/llms.txt

Initialize a new binary cache with specified configuration.

```APIDOC
## POST /_api/v1/cache-config/{cache_name}

### Description
Creates a new binary cache with the provided configuration.

### Method
POST

### Endpoint
/_api/v1/cache-config/{cache_name}

### Parameters
#### Path Parameters
- **cache_name** (string) - Required - The name for the new cache.

#### Request Body
- **is_public** (boolean) - Required - Whether the cache should be public.
- **keypair** (object) - Required - An object containing the cache's keypair.
  - **name** (string) - The name of the keypair.
  - **secret** (string) - The private key.
  - **public** (string) - The public key.
- **store_dir** (string) - Required - The Nix store directory path.
- **priority** (integer) - Optional - The priority of the cache (defaults to 50).
- **upstream_cache_key_names** (array of strings) - Optional - List of upstream cache key names.

### Request Example
```json
{
  "is_public": true,
  "keypair": {
    "name": "my-cache",
    "secret": "my-cache:base64privatekey...",
    "public": "my-cache:base64publickey..."
  },
  "store_dir": "/nix/store",
  "priority": 50,
  "upstream_cache_key_names": ["cache.nixos.org-1"]
}
```
```

--------------------------------

### Configure Attic Chunking Parameters (TOML)

Source: https://github.com/zhaofengli/attic/blob/main/book/src/admin-guide/chunking.md

This snippet shows the TOML configuration for Attic's chunking feature. It includes settings for the NAR size threshold, and the preferred minimum, average, and maximum chunk sizes. Changing these values after initial setup can impact deduplication efficiency.

```toml
# Data chunking
#
# Warning: If you change any of the values here, it will be
# difficult to reuse existing chunks for newly-uploaded NARs
# since the cutpoints will be different. As a result, the
# deduplication ratio will suffer for a while after the change.
[chunking]
# The minimum NAR size to trigger chunking
#
# If 0, chunking is disabled entirely for newly-uploaded NARs.
# If 1, all newly-uploaded NARs are chunked.
nar-size-threshold = 131072 # chunk files that are 128 KiB or larger

# The preferred minimum size of a chunk, in bytes
min-size = 65536            # 64 KiB

# The preferred average size of a chunk, in bytes
avg-size = 131072           # 128 KiB

# The preferred maximum size of a chunk, in bytes
max-size = 262144           # 256 KiB

```

--------------------------------

### Configure Attic Server using Environment Variables

Source: https://context7.com/zhaofengli/attic/llms.txt

This bash script demonstrates how to configure the Attic server using environment variables, particularly for sensitive credentials. It shows how to export the entire configuration as a base64 encoded string or override specific settings like the database URL and JWT secret.

```bash
# Export configuration as base64
export ATTIC_SERVER_CONFIG_BASE64=$(cat server.toml | base64 -w0)

# Override specific settings
export ATTIC_SERVER_DATABASE_URL="postgresql://user:pass@host/db"
export ATTIC_SERVER_TOKEN_HS256_SECRET_BASE64="c2VjcmV0a2V5"

# Start server
atticd

```

--------------------------------

### Deploy Attic as a NixOS Service

Source: https://context7.com/zhaofengli/attic/llms.txt

This Nix language configuration defines how to enable and configure the Attic service within a NixOS environment. It specifies service settings such as listen address, allowed hosts, API endpoint, database connection, S3 storage details, chunking, compression, and garbage collection intervals. It also shows how to manage credentials via a separate file.

```nix
{ config, pkgs, ... }:

{
  services.atticd = {
    enable = true;

    settings = {
      listen = "[::]:8080";
      allowed-hosts = [ "cache.example.com" ];
      api-endpoint = "https://cache.example.com/";

      database.url = "postgresql:///attic?host=/run/postgresql";

      storage = {
        type = "s3";
        region = "us-east-1";
        bucket = "attic-cache";
        credentials = {
          access_key_id = "AKIAIOSFODNN7EXAMPLE";
          secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY";
        };
      };

      chunking = {
        nar-size-threshold = 65536;
        min-size = 16384;
        avg-size = 65536;
        max-size = 262144;
      };

      compression = {
        type = "zstd";
        level = 8;
      };

      garbage-collection = {
        interval = "12 hours";
        default-retention-period = "15552000";
      };
    };

    credentialsFile = "/run/secrets/attic-credentials";
  };

  # Credentials file contains:
  # ATTIC_SERVER_TOKEN_HS256_SECRET_BASE64=base64secret...
}

```

--------------------------------

### Upload Store Path using cURL with Preamble Method

Source: https://context7.com/zhaofengli/attic/llms.txt

This cURL command uploads a store path's NAR archive, accommodating larger metadata payloads by prepending it to the NAR data. The `X-Attic-Nar-Info-Preamble-Size` header specifies the metadata size. This method is suitable when the NAR info is too large for a standard HTTP header.

```bash
# Upload using preamble method (for large metadata)
NAR_INFO='{"cache":"my-cache",...}'
NAR_INFO_SIZE=${#NAR_INFO}

(echo -n "${NAR_INFO}"; cat path.nar) | \
  curl -X PUT https://cache.example.com/_api/v1/upload-path \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "X-Attic-Nar-Info-Preamble-Size: ${NAR_INFO_SIZE}" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @-
```

--------------------------------

### NixOS Configuration for Attic Server

Source: https://github.com/zhaofengli/attic/blob/main/book/src/admin-guide/deployment/nixos.md

Configures the Attic Server service on NixOS. This includes enabling the service, specifying the environment file for credentials, and setting server configurations for listening address, JWT, and data chunking parameters (NAR size threshold, min, average, and max chunk sizes).

```nix
{ services.atticd = {
    enable = true;

    # Replace with absolute path to your environment file
    environmentFile = "/etc/atticd.env";

    settings = {
      listen = "[::]:8080";

      jwt = { };

      # Data chunking
      #
      # Warning: If you change any of the values here, it will be
      # difficult to reuse existing chunks for newly-uploaded NARs
      # since the cutpoints will be different. As a result, the
      # deduplication ratio will suffer for a while after the change.
      chunking = {
        # The minimum NAR size to trigger chunking
        #
        # If 0, chunking is disabled entirely for newly-uploaded NARs.
        # If 1, all NARs are chunked.
        nar-size-threshold = 64 * 1024; # 64 KiB

        # The preferred minimum size of a chunk, in bytes
        min-size = 16 * 1024; # 16 KiB

        # The preferred average size of a chunk, in bytes
        avg-size = 64 * 1024; # 64 KiB

        # The preferred maximum size of a chunk, in bytes
        max-size = 256 * 1024; # 256 KiB
      };
    };
  };
}
```

--------------------------------

### Attic CLI: Configure Nix to Use Cache

Source: https://context7.com/zhaofengli/attic/llms.txt

Explains how to configure the Nix package manager to use a specific Attic cache as a substituter. The `attic use` command modifies `nix.conf` and `netrc` files to include the cache's substituter URL and public key, and authentication token.

```bash
# Configure Nix with cache
attic use my-server:my-cache

# This updates:
# - ~/.config/nix/nix.conf with substituter and public key
# - ~/.config/nix/netrc with authentication token

# Result in nix.conf:
# extra-substituters = https://cache.example.com/my-cache
# extra-trusted-public-keys = my-cache:abc123...

# Result in netrc:
# machine cache.example.com password eyJhbGc...
```

--------------------------------

### Configure Local Storage for Development

Source: https://context7.com/zhaofengli/attic/llms.txt

This TOML configuration sets up Attic to use the local filesystem for storage, which is ideal for development environments. It specifies the listen address, database URL (using SQLite), local storage path, chunking parameters, compression settings, and JWT signing secret.

```toml
listen = "127.0.0.1:8080"
api-endpoint = "http://localhost:8080/"

[database]
url = "sqlite:///var/lib/atticd/server.db"

[storage]
type = "local"
path = "/var/lib/atticd/storage"

[chunking]
nar-size-threshold = 65536
min-size = 16384
avg-size = 65536
max-size = 262144

[compression]
type = "zstd"
level = 6

[jwt.signing]
token-hs256-secret-base64 = "YmFzZTY0ZW5jb2RlZHNlY3JldA=="

```

--------------------------------

### Import and Verify Signatures in Rust

Source: https://context7.com/zhaofengli/attic/llms.txt

Loads existing Ed25519 keypairs and public keys to verify NAR archive signatures. It demonstrates importing keys from string formats and verifying signatures against messages. Requires 'attic::signing' module.

```rust
use attic::signing::{NixKeypair, NixPublicKey};

fn main() -> attic::error::AtticResult<()> {
    // Import keypair from canonical format
    let keypair_str = "my-cache:base64keypair...";
    let keypair = NixKeypair::from_str(keypair_str)?;

    // Import public key
    let public_key_str = "cache.nixos.org-1:base64pubkey...";
    let public_key = NixPublicKey::from_str(public_key_str)?;

    // Verify signature
    let message = b"sha256:0123456789abcdef...";
    let signature = "cache.nixos.org-1:base64sig...";

    match public_key.verify(message, signature) {
        Ok(_) => println!("Signature valid"),
        Err(e) => println!("Signature invalid: {}", e),
    }

    // Self-sign and verify
    let my_sig = keypair.sign(message);
    keypair.public_key().verify(message, &my_sig)?;
    println!("Self-verification successful");

    Ok(())
}

```

--------------------------------

### Use Token with Nix (Bash)

Source: https://context7.com/zhaofengli/attic/llms.txt

Configures Nix to authenticate with an Attic cache using the `.netrc` file and `nix.conf`. It shows how to add the cache machine's hostname and the JWT as the password in `.netrc`, and then configure the substituter and trusted public key in `nix.conf`. Finally, it provides a command to test the substitution.

```bash
# Add to ~/.config/nix/netrc
cat >> ~/.config/nix/netrc <<EOF
machine cache.example.com
password eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
EOF

chmod 600 ~/.config/nix/netrc

# Add substituter to ~/.config/nix/nix.conf
cat >> ~/.config/nix/nix.conf <<EOF
extra-substituters = https://cache.example.com/my-cache
extra-trusted-public-keys = my-cache:base64publickey...
EOF

# Test substitution
nix build nixpkgs#hello --print-build-logs

```

--------------------------------

### Configure Production with S3 Storage and RSA Signing

Source: https://context7.com/zhaofengli/attic/llms.txt

This TOML configuration is designed for production environments, utilizing S3 for storage and RSA keys for JWT signing. It includes settings for listen address, allowed hosts, API endpoints, database connection (PostgreSQL), S3 bucket details, chunking, compression, garbage collection, and JWT signing credentials.

```toml
listen = "[::]:8080"
allowed-hosts = ["cache.example.com", "cache-mirror.example.com"]
api-endpoint = "https://cache.example.com/"
substituter-endpoint = "https://cache.example.com/"
soft-delete-caches = false
require-proof-of-possession = true
max-nar-info-size = 1048576

[database]
url = "postgresql://attic:pass@db.internal:5432/attic?sslmode=require"
heartbeat = true

[storage]
type = "s3"
region = "eu-west-1"
bucket = "production-attic-cache"

[storage.credentials]
access_key_id = "AKIAIOSFODNN7EXAMPLE"
secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

[chunking]
nar-size-threshold = 131072
min-size = 32768
avg-size = 131072
max-size = 524288

[compression]
type = "zstd"
level = 10

[garbage-collection]
interval = "6 hours"
default-retention-period = "15552000"  # 180 days

[jwt]
token-bound-issuer = "https://auth.example.com"
token-bound-audiences = ["attic-cache"]

[jwt.signing]
token-rs256-secret-base64 = "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQ..."

```

--------------------------------

### Create Cache using cURL

Source: https://context7.com/zhaofengli/attic/llms.txt

This cURL command is used to initialize and create a new binary cache within the Attic system. It requires specifying cache details like visibility, store directory, priority, and upstream references, along with a generated keypair for signing. The request body is a JSON object containing these parameters.

```bash
# Generate keypair for new cache
KEYPAIR=$(cat <<EOF | jq -c
{
  "name": "my-cache",
  "secret": "my-cache:base64privatekey...",
  "public": "my-cache:base64publickey..."
}
EOF
)

curl -X POST https://cache.example.com/_api/v1/cache-config/my-cache \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"is_public\": true,
    \"keypair\": ${KEYPAIR},
    \"store_dir\": \"/nix/store\",
    \"priority\": 50,
    \"upstream_cache_key_names\": [\"cache.nixos.org-1\"]
  }"
```

--------------------------------

### Download NAR Info using cURL

Source: https://context7.com/zhaofengli/attic/llms.txt

This cURL command retrieves the `.narinfo` metadata file for a specific store path from an Attic cache. The `.narinfo` file contains essential information about the store path, such as its references, system, and NAR hash, which is crucial for Nix to manage dependencies and reconstruct paths.

```bash
# Get .narinfo file
curl https://cache.example.com/my-cache/abc123xyz.narinfo
```

--------------------------------

### Upload Store Path using cURL with X-Attic-Nar-Info Header

Source: https://context7.com/zhaofengli/attic/llms.txt

This cURL command uploads a store path's NAR archive to the Attic cache. It utilizes the `X-Attic-Nar-Info` header for small metadata payloads. The command sends the NAR binary data and expects a JSON response indicating the upload status and deduplication information.

```bash
# Upload using X-Attic-Nar-Info header (for small metadata)
NAR_INFO=$(cat <<EOF | jq -c
{
  "cache": "my-cache",
  "store_path_hash": "abc123xyz",
  "store_path": "/nix/store/abc123xyz-hello-2.12",
  "references": ["/nix/store/xyz789-glibc-2.35"],
  "system": "x86_64-linux",
  "deriver": "/nix/store/drv123-hello-2.12.drv",
  "sigs": ["cache.example.com-1:base64sig..."],
  "ca": null,
  "nar_hash": "sha256:0123456789abcdef...",
  "nar_size": 1048576
}
EOF
)

curl -X PUT https://cache.example.com/_api/v1/upload-path \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Attic-Nar-Info: ${NAR_INFO}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @path.nar

# Response
{
  "kind": "Deduplicated",
  "file_size": 1048576,
  "frac_deduplicated": 0.85
}
```
Tokens:
Raw