nixos-servers/docs/plans/garage-s3-storage.md

Garage S3 Storage Server

Overview

Deploy a Garage instance for self-hosted S3-compatible object storage.

Garage Basics

• S3-compatible distributed object storage designed for self-hosting
• Supports per-key, per-bucket permissions (read/write/owner)
• Keys without explicit grants have no access

NixOS Module

Available as services.garage with these key options:

• services.garage.enable - Enable the service
• services.garage.package - Must be set explicitly
• services.garage.settings - Freeform TOML config (replication mode, ports, RPC, etc.)
• services.garage.settings.metadata_dir - Metadata storage (SSD recommended)
• services.garage.settings.data_dir - Data block storage (supports multiple dirs since v0.9)
• services.garage.environmentFile - For secrets like GARAGE_RPC_SECRET
• services.garage.logLevel - error/warn/info/debug/trace

The NixOS module only manages the server daemon. Buckets and keys are managed externally.

Bucket/Key Management

No declarative NixOS options for buckets or keys. Two options:

1. Terraform provider - jkossis/terraform-provider-garage manages buckets, keys, and permissions via the Garage Admin API v2. Could live in terraform/garage/ similar to terraform/vault/.
2. CLI - garage key create, garage bucket create, garage bucket allow

Integration Ideas

• Store Garage API keys in Vault, fetch via vault.secrets on consuming hosts
• Terraform manages both Vault secrets and Garage buckets/keys
• Enable admin API with token for Terraform provider access
• Add Prometheus metrics scraping (Garage exposes metrics endpoint)

Open Questions

• Single-node or multi-node replication?
• Which host to deploy on?
• What to store? (backups, media, app data)
• Expose via HTTP proxy or direct S3 API only?