tdpeuter/bos55-nix-config-cicd
1
Fork 0
forked from Bos55/nix-config
Code Pull requests 1 Releases Packages Activity Actions

docs(binary-cache): Add implementation documentation

Browse source
This commit is contained in:
Tibo De Peuter 2026-03-17 18:40:07 +01:00
parent 4f160adef3
commit a9d3469959
Signed by: tdpeuter
GPG key ID: 38297DE43F75FFE2
4 changed files with 459 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

81
docs/binary-cache/binary-cache-options.md Normal file
View file

@ -0,0 +1,81 @@
# Nix Binary Cache Options Comparison
This document provides a formal comparison of various binary cache solutions for Nix, to help decide on the best fit for your Homelab and external development machines.
## Overview of Options
| Option | Type | Backend | Multi-tenancy | Signing | Best For |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Attic** | Self-hosted Server | S3 / Local / PG | Yes | Server-side | Teams/Homelabs with multiple caches and tenants. |
| **Harmonia** | Self-hosted Server | Local Store | No | Server-side | Simple setups serving a single machine's store. |
| **nix-serve** | Self-hosted Server | Local Store | No | Server-side | Legacy/Basic setups. |
| **Cachix** | Managed SaaS | Hosted S3 | Yes | Cloud-managed | User who wants zero-maintenance and global speed. |
| **Simple HTTP/S3** | Static Files | S3 / Web Server | No | Client-side | Minimalist, low-cost static hosting. |
---
## Detailed Analysis
### 1. Attic (The "Modern" Choice)
Attic is a modern, high-performance Nix binary cache server written in Rust.
* **Benefits:**
* **Global Deduplication**: If multiple caches (tenants) contain the same binary, it's only stored once.
* **Multi-tenancy**: You can create separate, isolated caches for different projects or users.
* **Management CLI**: Comes with an excellent CLI (`attic login`, `attic use`, `attic push`) that makes client configuration trivial.
* **Automatic Signing**: The server manages the private keys and signs paths on the fly.
* **Garbage Collection**: Support for LRU-based garbage collection.
* **Downsides:**
* **Complexity**: Requires a PostgreSQL database and persistent storage (though it can run in Docker).
* **Overhead**: Might be slight overkill for a single-user homelab.
### 2. Harmonia (The "Speed" Choice)
Harmonia is a fast, lightweight server that serves the local `/nix/store` directly.
* **Benefits:**
* **Extreme Performance**: Written in Rust, supports zstd and `http-ranges` for streaming.
* **Simple Setup**: If you already have a "Build Server", you just run Harmonia on it to expose its store.
* **Modern**: Uses the `nix-daemon` protocol for better security/integration.
* **Downsides:**
* **Single Machine**: Only serves the store of the host it's running on.
* **No Multi-tenancy**: No isolation between different caches.
### 3. nix-serve (The "Classic" Choice)
The original Perl implementation for serving a Nix store.
* **Benefits:**
* **Compatibility**: Virtually every Nix system knows how to talk to it.
* **Downsides:**
* **Performance**: Slower than Rust alternatives; lacks native compression optimizations.
* **Maintenance**: Requires Nginx for HTTPS/IPv6 support.
### 4. Cachix (The "No-Maintenance" Choice)
A managed service that "just works".
* **Benefits:**
* **Zero Infrastructure**: No servers to manage.
* **Global Reach**: Uses a CDN for fast downloads everywhere.
* **Downsides:**
* **Cost**: Private caches usually require a subscription.
* **Privacy**: Your binaries are stored on third-party infrastructure.
### 5. Simple HTTP / S3 (The "Minimalist" Choice)
Pushing files to a bucket and serving them statically.
* **Benefits:**
* **Cheap/Offline**: No server process running.
* **Robust**: No database or service to crash.
* **Downsides:**
* **Static Signing**: You must sign binaries on the CI machine before pushing.
* **No GC**: Managing deletes in a static bucket is manual and prone to errors.
---
## Recommendation
For your requirement of **Homelab integration + External machines**, **Attic** remains the strongest candidate because:
1. **Ease of Client Setup**: Your personal machines only need to run `attic login` and `attic use` once.
2. **CI Synergy**: Gitea Actions can push to Attic using standard tokens without needing SSH access to the server's store.
3. **Sovereignty**: You keep all your data within your own infrastructure.
If you prefer something simpler that just "exposes" your existing build host, **Harmonia** is the runner-up.