digitalboard.core/roles/garage

Garage

Ansible role to deploy Garage S3-compatible object storage via Docker Compose, with declarative key/bucket provisioning and an optional WebUI behind htpasswd or authentik ForwardAuth.

Requirements

• Docker and Docker Compose installed on the target host
• Ansible collection: community.docker
• htpasswd (from apache2-utils / httpd-tools) when the WebUI is enabled and authentik ForwardAuth is not used
• Traefik with a shared garage_traefik_network (default proxy)

Role variables

Full spec with types and defaults: meta/argument_specs.yml. The most common overrides:

Service

• garage_s3_domains: FQDNs the S3 router accepts. The first entry is the canonical hostname; garage.toml derives the virtual-hosted-style S3 root_domain from it as .s3.<first-entry> (so buckets resolve under <bucket>.s3.<first-entry>).
• garage_web_domain, garage_webui_domain: separate hostnames for the S3-website endpoint and the console.
• garage_image, garage_replication_factor, garage_db_engine, garage_s3_region.

Required secrets

Generate with openssl rand -hex 32 (32 bytes / 64 hex chars):

• garage_rpc_secret: node-to-node RPC secret
• garage_admin_token: admin API token
• garage_metrics_token: metrics endpoint token

WebUI authentication

Three modes:

1. htpasswd (default): garage_webui_username / garage_webui_password in plaintext. The role hashes the password with htpasswd -nbBC 10, persists the hash on disk, and re-verifies with htpasswd -vbB so unchanged passwords don't churn the play.
2. authentik ForwardAuth: set garage_webui_authentik_forward_auth: true and garage_webui_authentik_forward_auth_url: "https://auth.example.com/outpost.goauthentik.io/auth/traefik". AUTH_USER_PASS is dropped from the container env so authentik is the only gate.
3. Disabled: garage_webui_enabled: false.

Layout bootstrap

Setting garage_bootstrap_enabled: true runs the bootstrap task, which joins the local node to the layout (zone: garage_bootstrap_zone, capacity: garage_bootstrap_capacity) on the first run. The check tolerates the 16-char truncation that garage layout show performs.

Declarative S3 keys and buckets

garage_s3_keys:
  - name: nextcloud
    buckets:
      - name: nextcloud-data
        permissions: [read, write]
  - name: backup
    buckets:
      - name: restic-prod
        permissions: [read, write, owner]

The role:

• Lists existing keys (garage key list), creates missing ones
• Lists existing buckets (garage bucket list), creates missing ones
• Reads current permissions via garage bucket info and runs garage bucket allow only when the current RWO flags for the key don't already match the desired permissions

stdout parsing is hardened against ANSI escapes and interleaved INFO log lines, so probe noise no longer produces spurious changes.

Dependencies

• Traefik network (garage_traefik_network, default proxy)
• Internal network (garage_internal_network, default internal)

Example playbook

- hosts: storage_servers
  roles:
    - role: digitalboard.core.garage
      vars:
        garage_s3_domains:
          - "storage.example.com"
          - "storage.int.example.com"
        garage_rpc_secret: "{{ vault_garage_rpc_secret }}"
        garage_admin_token: "{{ vault_garage_admin_token }}"
        garage_metrics_token: "{{ vault_garage_metrics_token }}"
        garage_bootstrap_enabled: true
        garage_webui_authentik_forward_auth: true
        garage_webui_authentik_forward_auth_url: "https://auth.example.com/outpost.goauthentik.io/auth/traefik"
        garage_s3_keys:
          - name: nextcloud
            buckets:
              - name: nextcloud-data
                permissions: [read, write]

License

MIT-0