---
argument_specs:
  main:
    short_description: Deploy Garage S3-compatible object storage via Docker Compose.
    description:
      - Renders a Compose stack for Garage with traefik labels, configures the
        node layout on first run, and (optionally) provisions S3 keys, buckets
        and per-key permissions declaratively.
      - The optional WebUI can be protected by classic htpasswd or by
        authentik ForwardAuth.
    options:
      docker_compose_base_dir:
        type: path
        default: /etc/docker/compose
      docker_volume_base_dir:
        type: path
        default: /srv/data
      garage_service_name:
        type: str
        default: garage
      garage_docker_compose_dir:
        type: path
        description: Defaults to C({{ docker_compose_base_dir }}/{{ garage_service_name }}).
      garage_docker_volume_dir:
        type: path
        description: Defaults to C({{ docker_volume_base_dir }}/{{ garage_service_name }}).

      garage_image:
        type: str
        default: dxflrs/garage:v2.1.0

      garage_s3_domains:
        type: list
        elements: str
        default: ['storage.local.test']
        description:
          - FQDNs the garage S3 router accepts. The first entry is the
            canonical domain and is used as the virtual-hosted-style
            C(root_domain) in C(garage.toml). Further entries cover internal
            C(*.int.*) names.
      garage_web_domain:
        type: str
        default: web.storage.local.test
        description: Hostname serving the S3-website endpoint.
      garage_webui_domain:
        type: str
        default: console.storage.local.test
        description: Hostname serving the WebUI console.

      garage_webui_enabled:
        type: bool
        default: true
      garage_webui_image:
        type: str
        default: khairul169/garage-webui:latest
      garage_webui_port:
        type: int
        default: 3909
      garage_webui_username:
        type: str
        default: admin
        description: htpasswd username. Ignored when C(garage_webui_authentik_forward_auth=true).
      garage_webui_password:
        type: str
        default: admin
        description:
          - Plaintext password; hashed with C(htpasswd -nbBC 10) and persisted
            on disk so re-runs don't churn. Ignored when authentik ForwardAuth
            is enabled.
      garage_webui_authentik_forward_auth:
        type: bool
        default: false
        description:
          - When true the C(AUTH_USER_PASS) env-var is dropped from the WebUI
            container and traefik attaches a ForwardAuth middleware pointing
            at the URL below. authentik is then the only gate; htpasswd is
            disabled.
      garage_webui_authentik_forward_auth_url:
        type: str
        default: ''
        description:
          - Required when C(garage_webui_authentik_forward_auth=true).
            Typically C(https://auth.example.com/outpost.goauthentik.io/auth/traefik).

      garage_s3_api_port:
        type: int
        default: 3900
      garage_s3_web_port:
        type: int
        default: 3902
      garage_admin_port:
        type: int
        default: 3903
      garage_rpc_port:
        type: int
        default: 3901

      garage_replication_factor:
        type: int
        default: 1
      garage_compression_level:
        type: int
        default: 1
      garage_db_engine:
        type: str
        choices: [lmdb, sqlite, sled]
        default: lmdb
      garage_s3_region:
        type: str
        default: us-east-1
      garage_rpc_secret:
        type: str
        required: true
        description: Hex secret for node-to-node RPC. Generate with C(openssl rand -hex 32).
      garage_admin_token:
        type: str
        required: true
      garage_metrics_token:
        type: str
        required: true

      garage_traefik_network:
        type: str
        default: proxy
      garage_internal_network:
        type: str
        default: internal
      garage_use_ssl:
        type: bool
        default: true

      garage_bootstrap_enabled:
        type: bool
        default: false
        description: When true the bootstrap task ensures the node is in the layout.
      garage_bootstrap_zone:
        type: str
        default: dc1
        description: Zone label assigned during layout bootstrap.
      garage_bootstrap_capacity:
        type: str
        default: 1G
        description: Capacity string passed to C(garage layout assign -c).

      garage_s3_keys:
        type: list
        elements: dict
        default: []
        description:
          - Declarative key + bucket + permission provisioning. The role
            creates missing keys, missing buckets, and runs C(bucket allow)
            only when the current RWO flags for a given key don't match.
        options:
          name:
            type: str
            required: true
          buckets:
            type: list
            elements: dict
            description: Buckets this key gets access to.
            options:
              name:
                type: str
                required: true
              permissions:
                type: list
                elements: str
                choices: [read, write, owner]
                required: true