Garage
======

Ansible role to deploy Garage S3-compatible object storage using Docker Compose.

Requirements
------------

- Docker and Docker Compose installed on the target host
- Ansible collection: `community.docker`
- Traefik reverse proxy (for external access)

Role Variables
--------------

Key variables defined in `defaults/main.yml`:

**Base Configuration:**
- `docker_compose_base_dir`: Base directory for Docker Compose files (default: `/etc/docker/compose`)
- `docker_volume_base_dir`: Base directory for Docker volumes (default: `/srv/data`)

**Garage Configuration:**
- `garage_service_name`: Service name (default: `garage`)
- `garage_image`: Garage Docker image (default: `dxflrs/garage:v2.1.0`)
- `garage_s3_domain`: Domain for S3 API endpoint (default: `storage.local.test`)
- `garage_web_domain`: Domain for S3 web endpoint (default: `web.storage.local.test`)
- `garage_webui_domain`: Domain for web console (default: `console.storage.local.test`)

**Garage Storage Configuration:**
- `garage_replication_factor`: Replication factor (default: `1`)
- `garage_compression_level`: Compression level (default: `1`)
- `garage_db_engine`: Database engine (default: `lmdb`)
- `garage_s3_region`: S3 region (default: `us-east-1`)

**Garage Ports:**
- `garage_s3_api_port`: S3 API port (default: `3900`)
- `garage_s3_web_port`: S3 web port (default: `3902`)
- `garage_admin_port`: Admin API port (default: `3903`)
- `garage_rpc_port`: RPC port (default: `3901`)

**Garage Security:**
- `garage_rpc_secret`: RPC secret for node communication
- `garage_admin_token`: Admin API token
- `garage_metrics_token`: Metrics API token

**Garage WebUI Configuration:**
- `garage_webui_enabled`: Enable web UI (default: `true`)
- `garage_webui_image`: WebUI Docker image (default: `khairul169/garage-webui:latest`)
- `garage_webui_port`: WebUI port (default: `3909`)
- `garage_webui_username`: WebUI username (default: `admin`)
- `garage_webui_password`: WebUI password in plaintext (default: `admin`)

**Traefik Configuration:**
- `garage_traefik_network`: Traefik network name (default: `proxy`)
- `garage_internal_network`: Internal network name (default: `internal`)
- `garage_use_ssl`: Enable SSL (default: `true`)

Dependencies
------------

This role requires:
- Traefik reverse proxy to be configured and the `proxy` network to be created
- `htpasswd` utility (from `apache2-utils` package) for generating bcrypt password hashes

Example Playbook
----------------

```yaml
- hosts: storage_servers
  roles:
    - role: garage
      vars:
        garage_s3_domain: "storage.example.com"
        garage_rpc_secret: "your-secure-rpc-secret"
        garage_admin_token: "your-admin-token"
        garage_webui_enabled: true
        garage_webui_username: "admin"
        garage_webui_password: "secure-password"
```

**Note:** The WebUI password is specified in plaintext and will be automatically hashed using bcrypt during deployment. The role uses `htpasswd` to generate a secure bcrypt hash that is then properly escaped for use in Docker Compose.

Post-Installation
-----------------

After deployment, you need to configure the Garage cluster:

1. Connect to the node and get the node ID:
   ```bash
   docker exec -ti garage /garage node id
   ```

2. Configure the node layout:
   ```bash
   docker exec -ti garage /garage layout assign -z dc1 -c 1G <node-id>
   docker exec -ti garage /garage layout apply --version 1
   ```

3. Create a key for S3 access:
   ```bash
   docker exec -ti garage /garage key create my-key
   ```

4. Create a bucket:
   ```bash
   docker exec -ti garage /garage bucket create my-bucket
   docker exec -ti garage /garage bucket allow my-bucket --read --write --key my-key
   ```

License
-------

MIT-0