Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
H

harmonia

> 编程语言
Open source

Nix binary cache implemented in rust (maintainer: @Mic92)

567 stars0 likes1 views
WebsiteGitHub

About

Nix binary cache implemented in rust (maintainer: @Mic92)

harmonia

Harmonia is a binary cache for nix that serves your /nix/store as a binary cache over http. It's written in Rust for speed.

Features

  • http-ranges support for nar file streaming
  • streaming build logs
  • .ls file streaming
    • Note: doesn't contain narOffset in json response but isn't needed for nix-index
  • Add /serve// endpoint to allow serving the content of package. Also discovers index.html to allow serving websites directly from the nix store.
  • Content is compressed transparently with zstd.
  • Builtin TLS: when no frontend webserver is used, Harmonia can also provide TLS encryption

Configuration for public binary cache on NixOS

Using NixOS stable (from nixpkgs)

There is a module for harmonia in nixpkgs. The following example set's up harmonia as a public binary cache using nginx as a frontend webserver with https encryption:

…

Using the flake version (latest features)

To use the latest version with all features, import the harmonia flake:

…

You can use the binary cache on a different machine using the following NixOS configuration:

nix
{
  nix.settings = {
    substituters = [ "https://cache.yourdomain.tld" ];
    # FIXME replace the key with the content of /var/lib/secrets/harmonia.pub
    trusted-public-keys = [ "cache.yourdomain.tld-1:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" ];
  };
}

Configuration format

Configuration is done via a toml file. Hint: You don't need to interface with the configuration directly in case you are using the NixOS module. The location of the configuration file should be passed as env var CONFIG_FILE. If no config file is passed the following default values will be used:

…

Per default we wont sign any narinfo because we don't have a secret key, to enable this feature enable it by providing a path to a private key generated by nix-store --generate-binary-cache-key cache.example.com-1 /etc/nix/cache.secret /etc/nix/cache.pub

toml
# nix binary cache signing key
sign_key_paths = [ "/run/secrets/cache.secret" ]

Harmonia also reads the SIGN_KEY_PATHS environment variable which holds paths to secret keys separated by spaces. All paths provided by sign_key_paths config option and SIGN_KEY_PATHS environment variable will be used for signing.

TLS Configuration

Harmonia can serve content over HTTPS without requiring a reverse proxy. To enable TLS, specify the paths to your certificate and private key files in the configuration:

toml
# Path to TLS certificate (PEM format)
tls_cert_path = "/path/to/cert.pem"
# Path to TLS private key (PEM format)
tls_key_path = "/path/to/key.pem"

Requirements for TLS certificates:

  • Certificate must be in PEM format
  • Certificate must be X.509 v3 (rustls does not support older versions)
  • Private key can be in either PKCS#8 or RSA format
  • Both files must be readable by the harmonia process

Example generating a self-signed certificate for testing:

bash
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
  -subj "/C=US/ST=State/O=Organization/CN=cache.example.com"

Note: When TLS is enabled, harmonia will only accept HTTPS connections on the configured port.

Logging Configuration

Logging is handled by tracing and configured via the RUST_LOG environment variable using EnvFilter syntax (compatible with the familiar env_logger directives). The default filter is info. To only log errors use RUST_LOG=error, and to keep info messages while disabling actix access logging use RUST_LOG=info,actix_web::middleware=error.

Build

Whole application

bash
nix build -L

Get a development environment:

bash
nix develop

Run tests

bash
nix flake check -L

Prometheus Monitoring

Harmonia exposes Prometheus metrics at the /metrics endpoint for monitoring and observability.

Available Metrics

HTTP Request Metrics:

  • harmonia_http_requests_total - Total number of HTTP requests (labeled by method, path, and status code)
  • harmonia_http_request_duration_seconds - Request latency histogram with buckets ranging from 0.0001s to 1.0s

Grafana Dashboard

A pre-configured Grafana dashboard is available in the repository at harmonia-cache/harmonia-grafana-dashboard.json. This dashboard visualizes:

  • Request rate and latency patterns
  • HTTP status code distribution
  • Error rates and performance trends

You can import this dashboard into your Grafana instance to monitor your Harmonia deployment.

Example Prometheus Configuration

To scrape metrics from Harmonia, add the following to your Prometheus configuration:

yaml
scrape_configs:
  - job_name: 'harmonia'
    static_configs:
      - targets: ['your-harmonia-host:5000']

Contributing

See CONTRIBUTING.md for development setup, testing, and code style guidelines. For architecture details, see docs/architecture.

Inspiration

  • eris

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rustbuild-with-buildbot

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言