### Install Golang SDK

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/build/golang.md

Install the garage-admin-sdk-golang using the go get command. This is the first step to using the SDK.

```bash
go get git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang
```

--------------------------------

### Single-Node Garage Quickstart Script

Source: https://context7.com/deuxfleurs/garage/llms.txt

This bash script demonstrates how to generate a Garage configuration file and start a single-node instance. It also sets environment variables for auto-provisioning and verifies the status.

```bash
# Generate config
cat > garage.toml <<EOF
metadata_dir = "/tmp/meta"
data_dir = "/tmp/data"
db_engine = "sqlite"
replication_factor = 1
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "$(openssl rand -hex 32)"
[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"
[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
[admin]
api_bind_addr = "[::]:3903"
admin_token = "$(openssl rand -base64 32)"
EOF

# Set env for auto-provisioning
export GARAGE_CONFIG_FILE=$(pwd)/garage.toml
export GARAGE_DEFAULT_ACCESS_KEY="GK$(openssl rand -hex 16)"
export GARAGE_DEFAULT_SECRET_KEY="$(openssl rand -hex 32)"
export GARAGE_DEFAULT_BUCKET="default-bucket"

# Start: auto-configures layout and creates default key+bucket
garage server --single-node --default-bucket

# Verify
garage status
# ==== HEALTHY NODES ====
# ID                Hostname  Address         Tags       Zone  Capacity  DataAvail         Version
# 563e1ac825ee3323  linuxbox  127.0.0.1:3901  [default]  dc1   19.9 GiB  19.5 GiB (97.6%)  v2.3.0

```

--------------------------------

### Setup Virtual Machines with Vagrant

Source: https://github.com/deuxfleurs/garage/blob/main-v2/script/jepsen.garage/README.md

Use this command to provision the necessary virtual machines for running Jepsen tests. Ensure Vagrant and VirtualBox are installed and configured.

```bash
vagrant up
```

--------------------------------

### Golang SDK Administration Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/build/golang.md

A comprehensive example demonstrating initialization, node management, key operations, and bucket management using the Golang SDK. Ensure the garage service is running locally.

```go
package main

import (
    "context"
    "fmt"
    "os"
    "strings"
    garage "git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang"
)

func main() {
    // Initialization
    configuration := garage.NewConfiguration()
    configuration.Host = "127.0.0.1:3903"
    client := garage.NewAPIClient(configuration)
    ctx := context.WithValue(context.Background(), garage.ContextAccessToken, "s3cr3t")

    // Nodes
    fmt.Println("--- nodes ---")
    nodes, _, _ := client.NodesApi.GetNodes(ctx).Execute()
    fmt.Fprintf(os.Stdout, "First hostname: %v\n", nodes.KnownNodes[0].Hostname)
    capa := int64(1000000000)
    change := []garage.NodeRoleChange{
	    garage.NodeRoleChange{NodeRoleUpdate: &garage.NodeRoleUpdate {
	        Id: *nodes.KnownNodes[0].Id,
	        Zone: "dc1",
	        Capacity: *garage.NewNullableInt64(&capa),
	        Tags: []string{ "fast", "amd64" },
	    }},
    }
    staged, _, _ := client.LayoutApi.AddLayout(ctx).NodeRoleChange(change).Execute()
    msg, _, _ := client.LayoutApi.ApplyLayout(ctx).LayoutVersion(*garage.NewLayoutVersion(staged.Version + 1)).Execute()
    fmt.Printf(strings.Join(msg.Message, "\n")) // Layout configured

    health, _, _ := client.NodesApi.GetHealth(ctx).Execute()
    fmt.Printf("Status: %s, nodes: %v/%v, storage: %v/%v, partitions: %v/%v\n", health.Status, health.ConnectedNodes, health.KnownNodes, health.StorageNodesOk, health.StorageNodes, health.PartitionsAllOk, health.Partitions)

    // Key
    fmt.Println("\n--- key ---")
    key := "openapi-key"
    keyInfo, _, _ := client.KeyApi.AddKey(ctx).AddKeyRequest(garage.AddKeyRequest{Name: *garage.NewNullableString(&key) }).Execute()
    defer client.KeyApi.DeleteKey(ctx).Id(*keyInfo.AccessKeyId).Execute()
    fmt.Printf("AWS_ACCESS_KEY_ID=%s\nAWS_SECRET_ACCESS_KEY=%s\n", *keyInfo.AccessKeyId, *keyInfo.SecretAccessKey.Get())

    id := *keyInfo.AccessKeyId
    canCreateBucket := true
    updateKeyRequest := *garage.NewUpdateKeyRequest()
    updateKeyRequest.SetName("openapi-key-updated")
    updateKeyRequest.SetAllow(garage.UpdateKeyRequestAllow { CreateBucket: &canCreateBucket })
    update, _, _ := client.KeyApi.UpdateKey(ctx).Id(id).UpdateKeyRequest(updateKeyRequest).Execute()
    fmt.Printf("Updated %v with key name %v\n", *update.AccessKeyId, *update.Name)

    keyList, _, _ := client.KeyApi.ListKeys(ctx).Execute()
    fmt.Printf("Keys count: %v\n", len(keyList))

    // Bucket
    fmt.Println("\n--- bucket ---")
    global_name := "global-ns-openapi-bucket"
    local_name := "local-ns-openapi-bucket"
    bucketInfo, _, _ := client.BucketApi.CreateBucket(ctx).CreateBucketRequest(garage.CreateBucketRequest{
        GlobalAlias: &global_name,
        LocalAlias: &garage.CreateBucketRequestLocalAlias {
            AccessKeyId: keyInfo.AccessKeyId,
	    Alias: &local_name,
        },
    }).Execute()
    defer client.BucketApi.DeleteBucket(ctx).Id(*bucketInfo.Id).Execute()
    fmt.Printf("Bucket id: %s\n", *bucketInfo.Id)

    updateBucketRequest := *garage.NewUpdateBucketRequest()
    website := garage.NewUpdateBucketRequestWebsiteAccess()
    website.SetEnabled(true)
    website.SetIndexDocument("index.html")
    website.SetErrorDocument("errors/4xx.html")
    updateBucketRequest.SetWebsiteAccess(*website)
    quotas := garage.NewUpdateBucketRequestQuotas()
    quotas.SetMaxSize(1000000000)
    quotas.SetMaxObjects(999999999)
    updateBucketRequest.SetQuotas(*quotas)
    updatedBucket, _, _ := client.BucketApi.UpdateBucket(ctx).Id(*bucketInfo.Id).UpdateBucketRequest(updateBucketRequest).Execute()
    fmt.Printf("Bucket %v website activation: %v\n", *updatedBucket.Id, *updatedBucket.WebsiteAccess)

    bucketList, _, _ := client.BucketApi.ListBuckets(ctx).Execute()
    fmt.Printf("Bucket count: %v\n", len(bucketList))
}

```

--------------------------------

### Install Garage on FreeBSD

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/binary-packages.md

Install the Garage package on FreeBSD using the pkg utility.

```bash
pkg install garage
```

--------------------------------

### Install Garage Administration SDK

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/build/javascript.md

Install the Garage Administration SDK using npm. This command fetches the SDK directly from the Git repository.

```bash
npm install --save git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-js.git
```

--------------------------------

### Install Garage on NixOS

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/binary-packages.md

Use nix-shell to install the Garage package on NixOS.

```bash
nix-shell -p garage
```

--------------------------------

### Full Garage TOML Configuration Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/reference-manual/configuration.md

This example demonstrates all possible configuration options for the garage daemon in a TOML file. It covers settings for replication, data directories, database, caching, RPC, discovery, S3 API, S3 web, and admin interfaces.

```toml
replication_factor = 3
consistency_mode = "consistent"

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
metadata_snapshots_dir = "/var/lib/garage/snapshots"
metadata_fsync = true
data_fsync = false
disable_scrub = false
use_local_tz = false
metadata_auto_snapshot_interval = "6h"

db_engine = "lmdb"

block_size = "1M"
block_ram_buffer_max = "256MiB"
block_max_concurrent_reads = 16
block_max_concurrent_writes_per_request =10
lmdb_map_size = "1T"

compression_level = 1

rpc_secret = "4425f5c26c5e11581d3223904324dcb5b5d5dfb14e5e7f35e38c595424f5f1e6"
rpc_bind_addr = "[::]:3901"
rpc_bind_outgoing = false
rpc_public_addr = "[fc00:1::1]:3901"
# or set rpc_public_adr_subnet to filter down autodiscovery to a subnet:
# rpc_public_addr_subnet = "2001:0db8:f00:b00:/64"


allow_world_readable_secrets = false

bootstrap_peers = [
    "563e1ac825ee3323aa441e72c26d1030d6d4414aeb3dd25287c531e7fc2bc95d@[fc00:1::1]:3901",
    "86f0f26ae4afbd59aaf9cfb059eefac844951efd5b8caeec0d53f4ed6c85f332@[fc00:1::2]:3901",
    "681456ab91350f92242e80a531a3ec9392cb7c974f72640112f90a600d7921a4@[fc00:B::1]:3901",
    "212fd62eeaca72c122b45a7f4fa0f55e012aa5e24ac384a72a3016413fa724ff@[fc00:F::1]:3901",
]

allow_punycode = false

[consul_discovery]
api = "catalog"
consul_http_addr = "https://127.0.0.1:8500"
tls_skip_verify = false
service_name = "garage-daemon"

ca_cert = "/etc/consul/consul-ca.crt"
# for `agent` API mode, unset client_cert and client_key:
client_cert = "/etc/consul/consul-client.crt"
client_key = "/etc/consul/consul-key.crt"

# optionally enable `token` for authentication:
# token = "abcdef-01234-56789"

tags = [ "dns-enabled" ]
meta = { dns-acl = "allow trusted" }
datacenter = ["dc1", "dc2", "dc3"]

[kubernetes_discovery]
namespace = "garage"
service_name = "garage-daemon"
skip_crd = false


[s3_api]
api_bind_addr = "[::]:3900"
s3_region = "garage"
root_domain = ".s3.garage"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage"
add_host_to_metrics = true

[admin]
api_bind_addr = "0.0.0.0:3903"
metrics_token = "BCAdFjoa9G0KJR0WXnHHm7fs1ZAbfpI8iIZ+Z/a2NgI="
metrics_require_token = true
admin_token = "UkLeGWEvHnXBqnueR3ISEMWpOnm40jH2tM2HnnL/0F4="
trace_sink = "http://localhost:4317"

```

--------------------------------

### Example values.override.yaml for MicroK8s

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/kubernetes.md

An example configuration file for deploying Garage on MicroK8s, including S3 API ingress and custom persistence settings.

```yaml
garage:
  # Use only 2 replicas per object
  replicationFactor: 2

# Start 4 instances (StatefulSets) of garage
deployment:
  replicaCount: 4

# Override default storage class and size
persistence:
  meta:
    storageClass: "openebs-hostpath"
    size: 100Mi
  data:
    storageClass: "openebs-hostpath"
    size: 1Gi

ingress:
  s3:
    api:
      enabled: true
      className: "public"
      annotations:
        cert-manager.io/cluster-issuer: "letsencrypt-prod"
        nginx.ingress.kubernetes.io/proxy-body-size: 500m
      hosts:
        - host: s3-api.my-domain.com
          paths:
            - path: /
              pathType: Prefix
      tls:
        - secretName: garage-ingress-cert
          hosts:
            - s3-api.my-domain.com

```

--------------------------------

### Start Garage Daemon Instances

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/development/scripts.md

Spawns 3 Garage instances with configuration files. Inspect detailed configurations, including ports, in `/tmp/config.1` (or other instance numbers). Also starts a simple HTTPS reverse proxy on port 4443 using socat.

```bash
./script/dev-cluster.sh
```

--------------------------------

### Install Garage with Default Options

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/kubernetes.md

Deploy the Garage application on Kubernetes using the Helm chart with default configuration.

```bash
helm install --create-namespace --namespace garage garage ./garage
```

--------------------------------

### Install Garage with Custom Values

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/kubernetes.md

Deploy the Garage application with custom configurations specified in a values file.

```bash
helm install --create-namespace --namespace garage garage ./garage -f values.override.yaml
```

--------------------------------

### Install Garage Admin SDK for Python

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/build/python.md

Install the Garage Admin SDK from its Git repository. Requires Python 3.6+, pip, and setuptools.

```bash
pip3 install --user 'git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-python'
```

--------------------------------

### Datacenters Configuration Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/reference-manual/configuration.md

Example of how to specify a list of datacenters for Garage to use in a Consul WAN federation setup. This allows Garage to discover nodes across different datacenters.

```hcl
datacenters = ["dc1", "dc2", "dc3"]
```

--------------------------------

### Install Minio Python SDK

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/build/python.md

Install the Minio SDK using pip. This is required for S3 operations.

```bash
pip3 install minio
```

--------------------------------

### Install synapse-s3-storage-provider

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/apps/index.md

Install the S3 storage provider module for Synapse using pip.

```bash
pip3 install --user git+https://github.com/matrix-org/synapse-s3-storage-provider.git
```

--------------------------------

### Start Telemetry Test Stack

Source: https://github.com/deuxfleurs/garage/blob/main-v2/script/telemetry/README.md

Navigate to the telemetry directory and start the services using Docker Compose.

```bash
cd telemetry
docker-compose up
```

--------------------------------

### CreateAdminToken CLI Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/reference-manual/admin-api.md

Example of calling the CreateAdminToken API using the `garage json-api` CLI with a JSON body.

```APIDOC
## CreateAdminToken

### Description
Creates a new admin token.

### Method
`garage json-api`

### Parameters
#### Request Body
- **name** (string) - Required - The name for the new token.

### Request Example
```bash
$ garage json-api CreateAdminToken '{"name": "test"}'
```

### Request Example (stdin)
```bash
$ garage json-api CreateAdminToken -
{"name": "test"}
<EOF>
```
```

--------------------------------

### Run Ente Server with Docker

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/apps/index.md

Start the Ente server using Docker, mounting the configuration and credentials files.

```bash
docker run -d --name ente-server --restart unless-stopped -v /path/to/museum.yaml:/museum.yaml -v /path/to/credentials.yaml:/credentials.yaml -p 8080:8080 ghcr.io/ente-io/ente-server
```

--------------------------------

### Check Nix installation

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/development/devenv.md

Verify that Nix commands are available and working correctly.

```bash
nix-shell --version
nix-build --version
nix-env   --version
```

--------------------------------

### Launch Garage Server with Docker

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/quick-start/_index.md

Run Garage in a Docker container, mapping ports and mounting configuration. This example does not create persistent volumes.

```bash
docker run \
  -d \
  --name garage-container \
  -p 3900:3900 -p 3901:3901 -p 3902:3902 -p 3903:3903 \
  -v $(pwd)/garage.toml:/etc/garage.toml \
  -e GARAGE_DEFAULT_ACCESS_KEY \
  -e GARAGE_DEFAULT_SECRET_KEY \
  -e GARAGE_DEFAULT_BUCKET \
  dxflrs/garage:v2.3.0
  /garage server --single-node --default-bucket
```

--------------------------------

### Install Garage on Arch Linux

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/binary-packages.md

Install the Garage package from the official Arch Linux repositories.

```bash
pacman -S garage
```

--------------------------------

### GetAdminTokenInfo CLI Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/reference-manual/admin-api.md

Example of calling GetAdminTokenInfo using the `garage json-api` CLI with a query parameter passed in the JSON body.

```APIDOC
## GetAdminTokenInfo

### Description
Retrieves information about a specific admin token.

### Method
`garage json-api`

### Parameters
#### Request Body
- **id** (string) - Required - The ID of the token to retrieve information for.

### Request Example
```bash
$ garage json-api GetAdminTokenInfo '{"id":"b0e6e0ace2c0b2aca4cdb2de"}'
```
```

--------------------------------

### List Access Keys Response Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/admin-api.md

Example response body for the ListKeys endpoint, returning a list of API access keys with their IDs and names.

```json
[
  {
    "id": "GK31c2f218a2e44f485b94239e",
    "name": "test"
  },
  {
    "id": "GKe10061ac9c2921f09e4c5540",
    "name": "test2"
  }
]
```

--------------------------------

### List Buckets Response

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/admin-api.md

Example response format for listing all storage buckets in the cluster.

```json
[
  {
    "id": "70dc3bed7fe83a75e46b66e7ddef7d56e65f3c02f9f80b6749fb97eccb5e1033",
    "globalAliases": [
      "test2"
    ],
    "localAliases": []
  },
  {
    "id": "96470e0df00ec28807138daf01915cfda2bee8eccc91dea9558c0b4855b5bf95",
    "globalAliases": [
      "alex"
    ],
    "localAliases": []
  },
  {
    "id": "d7452a935e663fc1914f3a5515163a6d3724010ce8dfd9e4743ca8be5974f995",
    "globalAliases": [
      "test3"
    ],
    "localAliases": []
  },
  {
    "id": "e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b",
    "globalAliases": [],
    "localAliases": [
      {
        "accessKeyId": "GK31c2f218a2e44f485b94239e",
        "alias": "test"
      }
    ]
  }
]
```

--------------------------------

### Garage TOML Configuration Example

Source: https://context7.com/deuxfleurs/garage/llms.txt

This TOML file configures a production 3-node Garage cluster. Adjust paths, replication, and network settings as needed.

```toml
# /etc/garage.toml — production 3-node cluster example

metadata_dir = "/var/lib/garage/meta"      # fast SSD preferred
data_dir = "/var/lib/garage/data"          # large HDD
db_engine = "lmdb"                         # "lmdb" (default), "sqlite", or "fjall" (experimental)
metadata_auto_snapshot_interval = "6h"     # automatic LMDB snapshots for recovery

replication_factor = 3                     # store 3 copies across zones
consistency_mode = "consistent"            # "consistent" | "degraded" | "dangerous"

compression_level = 1                      # zstd level 1–19; "none" to disable
block_size = "1M"                          # increase to "10M" for large files on fast networks
block_ram_buffer_max = "256MiB"            # backpressure limit for async writes
block_max_concurrent_reads = 16            # HDD read backpressure
block_max_concurrent_writes_per_request = 10  # 3–10 for HDD, 10–30 for NVMe

rpc_secret = "4425f5c26c5e11581d3223904324dcb5b5d5dfb14e5e7f35e38c595424f5f1e6"  # openssl rand -hex 32
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "192.0.2.1:3901"        # this node's public IP

bootstrap_peers = [
    "563e1ac825ee3323aa441e72c26d1030d6d4414aeb3dd25287c531e7fc2bc95d@[fc00:1::1]:3901",
    "86f0f26ae4afbd59aaf9cfb059eefac844951efd5b8caeec0d53f4ed6c85f332@[fc00:1::2]:3901",
]

[s3_api]
api_bind_addr = "[::]:3900"
s3_region = "garage"
root_domain = ".s3.garage.example.com"    # enables vhost-style: mybucket.s3.garage.example.com

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.example.com"   # mybucket.web.garage.example.com
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
admin_token = "UkLeGWEvHnXBqnueR3ISEMWpOnm40jH2tM2HnnL/0F4="   # openssl rand -base64 32
metrics_token = "BCAdFjoa9G0KJR0WXnHHm7fs1ZAbfpI8iIZ+Z/a2NgI="
metrics_require_token = true
trace_sink = "http://localhost:4317"      # optional OpenTelemetry collector

```

--------------------------------

### Install Garage Binary

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/from-source.md

Copies the compiled release binary to a system-wide location, making the 'garage' command available in the shell.

```bash
sudo cp target/release/garage /usr/local/bin/garage
```

--------------------------------

### Initialize and Use Garage Administration API Client

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/build/javascript.md

Initialize the API client with the server address and set authentication. This example demonstrates fetching nodes from the API.

```javascript
const garage = require('garage_administration_api_v1garage_v0_9_0');

const api = new garage.ApiClient("http://127.0.0.1:3903/v1");
api.authentications['bearerAuth'].accessToken = "s3cr3t";

const [node, layout, key, bucket] = [
  new garage.NodesApi(api),
  new garage.LayoutApi(api),
  new garage.KeyApi(api),
  new garage.BucketApi(api),
];

node.getNodes().then((data) => {
  console.log(`nodes: ${Object.values(data.knownNodes).map(n => n.hostname)}`)
}, (error) => {
  console.error(error);
});
```

--------------------------------

### Get Cluster Status JSON Response

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/admin-api.md

This is an example response body for the GET /v2/GetClusterStatus API endpoint. It details the current status of the cluster, including node information and layout.

```json
{
  "layoutVersion": 5,
  "nodes": [
    {
      "id": "62b218d848e86a64f7fe1909735f29a4350547b54c4b204f91246a14eb0a1a8c",
      "role": {
        "id": "62b218d848e86a64f7fe1909735f29a4350547b54c4b204f91246a14eb0a1a8c",
        "zone": "dc1",
        "capacity": 100000000000,
        "tags": []
      },
      "addr": "10.0.0.3:3901",
      "hostname": "node3",
      "isUp": true,
      "lastSeenSecsAgo": 12,
      "draining": false,
      "dataPartition": {
        "available": 660270088192,
        "total": 873862266880
      },
      "metadataPartition": {
        "available": 660270088192,
        "total": 873862266880
      }
    },
    {
      "id": "a11c7cf18af297379eff8688360155fe68d9061654449ba0ce239252f5a7487f",
      "role": null,
      "addr": "10.0.0.2:3901",
      "hostname": "node2",
      "isUp": true,
      "lastSeenSecsAgo": 11,
      "draining": true,
      "dataPartition": {
        "available": 660270088192,
        "total": 873862266880
      },
      "metadataPartition": {
        "available": 660270088192,
        "total": 873862266880
      }
    },
    {
      "id": "a235ac7695e0c54d7b403943025f57504d500fdcc5c3e42c71c5212faca040a2",
      "role": {
        "id": "a235ac7695e0c54d7b403943025f57504d500fdcc5c3e42c71c5212faca040a2",
        "zone": "dc1",
        "capacity": 100000000000,
        "tags": []
      },
      "addr": "127.0.0.1:3904",
      "hostname": "lindy",
      "isUp": true,
      "lastSeenSecsAgo": 2,
      "draining": false,
      "dataPartition": {
        "available": 660270088192,
        "total": 873862266880
      },
      "metadataPartition": {
        "available": 660270088192,
        "total": 873862266880
      }
    },
    {
      "id": "b10c110e4e854e5aa3f4637681befac755154b20059ec163254ddbfae86b09df",
      "role": {
        "id": "b10c110e4e854e5aa3f4637681befac755154b20059ec163254ddbfae86b09df",
        "zone": "dc1",
        "capacity": 100000000000,
        "tags": []
      },
      "addr": "10.0.0.1:3901",
      "hostname": "node1",
      "isUp": true,
      "lastSeenSecsAgo": 3,
      "draining": false,
      "dataPartition": {
        "available": 660270088192,
        "total": 873862266880
      },
      "metadataPartition": {
        "available": 660270088192,
        "total": 873862266880
      }
    }
  ]
}
```

--------------------------------

### Get Cluster Health JSON Response

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/admin-api.md

This is an example response body for the GET /v2/GetClusterHealth API endpoint. It provides a summary of the cluster's health status, including node and partition connectivity.

```json
{
  "status": "degraded",
  "knownNodes": 3,
  "connectedNodes": 3,
  "storageNodes": 4,
  "storageNodesOk": 3,
  "partitions": 256,
  "partitionsQuorum": 256,
  "partitionsAllOk": 64
}
```

--------------------------------

### Create Nix Binary Cache Bucket and Enable Website Access

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/repositories.md

Set up a bucket for Nix binary caches, create a key, grant permissions, and enable website access. This allows Nix to fetch derivations from the bucket.

```bash
garage key create nix-key
garage bucket create nix.example.com
garage bucket allow nix.example.com --read --write --key nix-key
garage bucket website nix.example.com --allow
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/api/README.md

Run a simple HTTP server in the current directory to browse the documentation. Open http://localhost:8000/garage-admin-v0.html in your browser.

```shell
python3 -m http.server
```

--------------------------------

### Get Cluster Layout JSON Response

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/admin-api.md

Example response body for the GetClusterLayout endpoint, showing the current and staged cluster layout.

```json
{
  "version": 12,
  "roles": [
    {
      "id": "ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f",
      "zone": "dc1",
      "capacity": 10737418240,
      "tags": [
        "node1"
      ]
    },
    {
      "id": "4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff",
      "zone": "dc1",
      "capacity": 10737418240,
      "tags": [
        "node2"
      ]
    },
    {
      "id": "23ffd0cdd375ebff573b20cc5cef38996b51c1a7d6dbcf2c6e619876e507cf27",
      "zone": "dc2",
      "capacity": 10737418240,
      "tags": [
        "node3"
      ]
    }
  ],
  "stagedRoleChanges": [
    {
      "id": "e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b",
      "remove": false,
      "zone": "dc2",
      "capacity": 10737418240,
      "tags": [
        "node4"
      ]
    }
    {
      "id": "23ffd0cdd375ebff573b20cc5cef38996b51c1a7d6dbcf2c6e619876e507cf27",
      "remove": true,
      "zone": null,
      "capacity": null,
      "tags": null
    }
  ]
}
```

--------------------------------

### awscli Example Usage

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/quick-start/_index.md

Demonstrates basic awscli commands for interacting with Garage, including listing buckets, listing objects in a bucket, and copying a file from the local filesystem to Garage.

```bash
# list buckets
aws s3 ls
```

```bash
# list objects of a bucket
aws s3 ls s3://default-bucket
```

```bash
# copy from your filesystem to garage
aws s3 cp /proc/cpuinfo s3://default-bucket/cpuinfo.txt
```

--------------------------------

### DeleteBatch Request Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/k2v-spec.md

Use this JSON format to specify items for batch deletion within a bucket. Supports partitionKey, start, and singleItem for targeting.

```json
POST /my_bucket?delete HTTP/1.1

[
  {
    "partitionKey": "mailbox:OldMailbox",
  },
  {
    "partitionKey": "mailbox:INBOX",
    "start": "0018928321",
    "singleItem": true,
  },
]
```

--------------------------------

### PollRange Request Body Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/k2v-spec.md

JSON object for polling changes within a specific range of items in a partition. Includes optional fields like prefix, start, end, timeout, and seenMarker.

```json
{
  "prefix": null,
  "start": null,
  "end": null,
  "timeout": 300,
  "seenMarker": null,
}
```

--------------------------------

### Get Admin Token Info with JSON query parameters via garage json-api

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/reference-manual/admin-api.md

Admin API calls that would normally take query parameters in HTTP requests can accept them within a JSON object passed to `garage json-api`. This example shows how to pass an ID.

```bash
$ garage json-api GetAdminTokenInfo '{"id":"b0e6e0ace2c0b2aca4cdb2de"}'
```

--------------------------------

### List Partition Keys in Bucket

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/k2v-spec.md

Use this GET request to list partition keys in a bucket. You can filter and order the results using query parameters like prefix, start, end, limit, and reverse. The response provides counts of entries, conflicts, values, and bytes, which are eventually consistent.

```http
GET /my_bucket HTTP/1.1
```

```json
HTTP/1.1 200 OK

{
  prefix: null,
  start: null,
  end: null,
  limit: null,
  reverse: false,
  partitionKeys: [
    {
      pk: "keys",
      entries: 3043,
      conflicts: 0,
      values: 3043,
      bytes: 121720,
    },
    {
      pk: "mailbox:INBOX",
      entries: 42,
      conflicts: 1,
      values: 43,
      bytes: 142029,
    },
    {
      pk: "mailbox:Junk",
      entries: 2991
      conflicts: 0,
      values: 2991,
      bytes: 12019322,
    },
    {
      pk: "mailbox:Trash",
      entries: 10,
      conflicts: 0,
      values: 10,
      bytes: 32401,
    },
    {
      pk: "mailboxes",
      entries: 3,
      conflicts: 0,
      values: 3,
      bytes: 3019,
    },
  ],
  more: false,
  nextStart: null,
}
```

--------------------------------

### Install awscli

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/quick-start/_index.md

Install the awscli tool using pip if you have Python installed. Ensure you have awscli version >= 1.29.0 or >= 2.13.0.

```bash
python -m pip install --user awscli
```

--------------------------------

### Create Peertube Key and Buckets

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/apps/index.md

Create a new key for Peertube and two buckets for videos and playlists. Remember to save the Key ID and Secret key.

```bash
garage key create peertube-key
```

```bash
garage bucket create peertube-videos
garage bucket create peertube-playlists
```

--------------------------------

### Create Garage Resources for ejabberd

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/apps/index.md

These commands create a new key and a bucket in Garage, then grant the key read/write permissions to the bucket and enable website functionality. This setup is required for ejabberd's media storage.

```bash
garage key new --name ejabberd
```

```bash
garage bucket create objects.xmpp-server.fr
```

```bash
garage bucket allow objects.xmpp-server.fr --read --write --key ejabberd
```

```bash
garage bucket website --allow objects.xmpp-server.fr
```

--------------------------------

### Launch Garage Server (Single Node)

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/quick-start/_index.md

Use this command to launch the Garage server in a single-node configuration with a default bucket. Omit flags for manual configuration.

```bash
garage server --single-node --default-bucket
```

--------------------------------

### Install Nextcloud External Storage App

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/apps/index.md

Install the 'files_external' application for Nextcloud using the occ command-line tool.

```bash
php occ app:install files_external
```

--------------------------------

### Install Rust and Cargo on Debian

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/from-source.md

Installs the necessary Rust compiler and Cargo package manager on Debian-based systems.

```bash
sudo apt-get update
sudo apt-get install -y rustc cargo
```

--------------------------------

### Manually Publish Docker Container

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/development/release-process.md

Configure Docker authentication, platform, container name, and tag. Then, execute 'nix-shell --run to_docker' to build and push the Docker image.

```bash
export DOCKER_AUTH='{ "auths": { "https://index.docker.io/v1/": { "auth": "xxxx" }}}"
export DOCKER_PLATFORM='linux/amd64' # check GOARCH and GOOS from golang.org
export CONTAINER_NAME='me/amd64_garage'
export CONTAINER_TAG='handcrafted-1.0.0'

nix-shell --run to_docker
```

--------------------------------

### Configure Initial Access Credentials for Garage

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/quick-start/_index.md

Sets environment variables to automatically create a default access key, secret key, and bucket upon Garage startup. Useful for initial setup and testing.

```bash
export GARAGE_DEFAULT_ACCESS_KEY="GK$(openssl rand -hex 16)"
export GARAGE_DEFAULT_SECRET_KEY="$(openssl rand -hex 32)"
export GARAGE_DEFAULT_BUCKET="default-bucket"
```

--------------------------------

### GetClusterHealth CLI Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/reference-manual/admin-api.md

Example of calling the GetClusterHealth API using the `garage json-api` CLI without any parameters.

```APIDOC
## GetClusterHealth

### Description
Retrieves the health status of the cluster.

### Method
`garage json-api`

### Parameters
None

### Request Example
```bash
$ garage json-api GetClusterHealth
```

### Response Example
```json
{
  "connectedNodes": 3,
  "knownNodes": 3,
  "partitions": 256,
  "partitionsAllOk": 256,
  "partitionsQuorum": 256,
  "status": "healthy",
  "storageNodes": 3,
  "storageNodesOk": 3
}
```
```

--------------------------------

### Create a Garage Bucket

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/quick-start/_index.md

Create a new bucket in your Garage storage.

```bash
garage bucket create nextcloud-bucket
```

--------------------------------

### Install Garage using pixi on conda-forge

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/binary-packages.md

Install the Garage package globally using the pixi tool from the conda-forge channel.

```bash
pixi global install garage
```

--------------------------------

### UpdateAdminToken CLI Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/reference-manual/admin-api.md

Example of calling UpdateAdminToken using the `garage json-api` CLI with both query parameters and a JSON body.

```APIDOC
## UpdateAdminToken

### Description
Updates an existing admin token.

### Method
`garage json-api`

### Parameters
#### Request Body
- **id** (string) - Required - The ID of the token to update.
- **body** (object) - Required - The fields to update for the token.
  - **name** (string) - Optional - The new name for the token.

### Request Example
```bash
$ garage json-api UpdateAdminToken '{"id":"b0e6e0ace2c0b2aca4cdb2de", "body":{"name":"not a test"}}'
```
```

--------------------------------

### Initialize Garage Admin SDK Client

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/build/python.md

Configure and initialize the Garage Admin SDK client with the host URL and access token for your Garage instance.

```python
import garage_admin_sdk
from garage_admin_sdk.apis import *
from garage_admin_sdk.models import *

configuration = garage_admin_sdk.Configuration(
  host = "http://localhost:3903/v1",
  access_token = "s3cr3t"
)

# Init APIs
api = garage_admin_sdk.ApiClient(configuration)
nodes, layout, keys, buckets = NodesApi(api), LayoutApi(api), KeyApi(api), BucketApi(api)
```

--------------------------------

### DeleteItem Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/k2v-spec.md

Example of deleting a single item. The X-Garage-Causality-Token header is mandatory and must match the causality token from a previous read.

```http
DELETE /my_bucket/mailboxes?sort_key=INBOX HTTP/1.1
X-Garage-Causality-Token: opaquetoken123
```

```http
HTTP/1.1 204 NO CONTENT
```

--------------------------------

### Garage TOML Configuration Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/real-world.md

This TOML configuration sets up essential parameters for the Garage daemon, including storage directories, database engine, replication, compression, and network addresses for RPC and S3 APIs.

```toml
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "lmdb"
metadata_auto_snapshot_interval = "6h"

replication_factor = 3

compression_level = 2

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "<this node's public IP>:3901"
rpc_secret = "<RPC secret>"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage"
index = "index.html"
```

--------------------------------

### Install ejabberd mod_s3_upload Module

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/apps/index.md

Use this command to install the necessary module for ejabberd to interact with Garage. Ensure ejabberdctl is available in your PATH.

```bash
ejabberdctl module_install mod_s3_upload
```

--------------------------------

### Enable Website Mode on a Bucket

Source: https://context7.com/deuxfleurs/garage/llms.txt

Configure a bucket to serve static websites using the `garage bucket website` command. This can include specifying custom index and error documents.

```bash
# 1. Enable website mode on a bucket
garage bucket website --allow my-site
# or with custom index/error docs:
garage bucket website --allow my-site \
  --index-document index.html \
  --error-document 404.html
```

--------------------------------

### Configure Nix for Automatic Signing

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/repositories.md

Configure `nix.conf` on your builder to automatically sign packages at build time using the specified private key file.

```toml
secret-key-files = /etc/nix/cache-priv-key.pem
```

--------------------------------

### Manually Publish Static Binary to S3

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/development/release-process.md

Set AWS credentials, target architecture, and release tag/commit, then use 'nix-shell --run to_s3' to upload the built static binary to the garage S3 bucket.

```bash
export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=xxx
export DRONE_TAG=handcrafted-1.0.0 # or DRONE_COMMIT
export TARGET=x86_64-unknown-linux-musl

nix-shell --run to_s3
```

--------------------------------

### ReadItem Octet-Stream Request Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/drafts/k2v-spec.md

Example of a request to read an item with the Accept header set to application/octet-stream. This format is preferred for single values.

```http
GET /my_bucket/mailboxes?sort_key=INBOX HTTP/1.1
Accept: application/octet-stream
```

--------------------------------

### Create Garage Resources for Ente

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/apps/index.md

Create a bucket and a key specifically for Ente to use with Garage for photo storage. These commands initialize the necessary Garage resources.

```bash
garage bucket create ente
```

```bash
garage key create ente-key
```

--------------------------------

### Run Smoke Tests for Garage Tools

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/development/scripts.md

Execute a suite of basic tests on tools like minio client, awscli, and rclone. Ensure you are in a nix-shell or have all required tools installed before running. Logs are available at `/tmp/garage.log`.

```bash
nix-build # or cargo build
./script/test-smoke.sh
```

--------------------------------

### Install C Toolchain on Debian

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/from-source.md

Installs the essential C build tools required for compiling Rust projects with C dependencies on Debian-based systems.

```bash
sudo apt-get update
sudo apt-get install build-essential
```

--------------------------------

### Install Garage on Alpine Linux

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/binary-packages.md

Use this command to install the Garage package on Alpine Linux versions 3.17 and later. The default configuration is at /etc/garage/garage.toml.

```bash
apk add garage
```

--------------------------------

### Create Vector System Logs Key and Bucket

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/connect/observability.md

Use these commands to create a new access key for Vector and a bucket to store system logs. Ensure the key has read and write permissions for the bucket.

```bash
garage key new --name vector-system-logs
garage bucket create system-logs
garage bucket allow system-logs --read --write --key vector-system-logs
```

--------------------------------

### Complete Traefik Configuration Example

Source: https://github.com/deuxfleurs/garage/blob/main-v2/doc/book/cookbook/reverse-proxy.md

A comprehensive Traefik configuration file demonstrating entry points, TLS certificate resolution, router definitions with middleware, and service load balancing with health checks.

```toml
[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.myresolver.acme]
  email = "your-email@example.com"
  storage = "acme.json"
  [certificatesResolvers.myresolver.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"

[http.routers]
  [http.routers.garage-s3]
    rule = "Host(`s3.example.org`)"
    service = "garage-s3-service"
    entryPoints = ["websecure"]

  [http.routers.my_website]
    rule = "Host(`yoururl.example.org`)"
    service = "garage-web-service"
    middlewares = ["compression"]
    entryPoints = ["websecure"]

[http.services]
  [http.services.garage-s3-service.loadBalancer]
    [http.services.garage-s3-service.loadBalancer.healthCheck]
      path = "/health"
      port = "3903"
      #interval = "15s"
      #timeout = "2s"

  [http.services.garage-web-service.loadBalancer]
    [http.services.garage-web-service.loadBalancer.healthCheck]
      path = "/health"
      port = "3903"
      #interval = "15s"
      #timeout = "2s"

    [[http.services.garage-s3-service.loadBalancer.servers]]
      url = "http://xxx.xxx.xxx.xxx"
      port = 3900
    [[http.services.garage-s3-service.loadBalancer.servers]]
      url = "http://yyy.yyy.yyy.yyy"
      port = 3900
    [[http.services.garage-s3-service.loadBalancer.servers]]
      url = "http://zzz.zzz.zzz.zzz"
      port = 3900

    [[http.services.garage-web-service.loadBalancer.servers]]
      url = "http://xxx.xxx.xxx.xxx"
      port = 3902
    [[http.services.garage-web-service.loadBalancer.servers]]
      url = "http://yyy.yyy.yyy.yyy"
      port = 3902
    [[http.services.garage-web-service.loadBalancer.servers]]
      url = "http://zzz.zzz.zzz.zzz"
      port = 3902

[http.middlewares]
  [http.middlewares.compression.compress]

```