Garage

Holden can provision a Garage container for your app, providing S3-compatible object storage with automatic credential generation and a default bucket.

Enable Garage

Add garage to your needs block:

services:
  web:
    image: myapp:latest
    domain: myapp.example.com
    env:
      S3_ENDPOINT: ${needs.garage.url}
      S3_ACCESS_KEY: ${needs.garage.access_key}
      S3_SECRET_KEY: ${needs.garage.secret_key}
      S3_BUCKET: ${needs.garage.bucket}

needs:
  garage:

Available Variables

Variable	Description	Example
${needs.garage.url}	S3 API endpoint	http://needs-garage:3900
${needs.garage.access_key}	Access key ID	GKabc123... (26 chars)
${needs.garage.secret_key}	Secret access key	def456... (64 chars)
${needs.garage.admin_url}	Admin API endpoint	http://needs-garage:3902
${needs.garage.bucket}	Default bucket name	myapp (same as app-id)

Default Bucket

Holden automatically creates a bucket named after your app-id. This happens on container startup and is idempotent (safe to restart).

Container Details

• Image: ghcr.io/bikeshedder/garage-single-node:v2
• Network: Your app’s private network (holden-{app-id})
• Container name: {app-id}-needs-garage
• Volume: [@base_data_dir]/{app-id}/garage → /var/lib/garage
• Ports: 3900 (S3 API), 3902 (Admin)

Health Checks

Holden waits for Garage to be ready before starting your app services.

Command: garage status (checks RPC connectivity)

• Start period: 10 seconds
• Timeout: 5 seconds per attempt
• Retries: 10 attempts with 3-second intervals