From 42055930eddfacfc24f98208f25e362e77e25823 Mon Sep 17 00:00:00 2001
From: Noooste <83548733+Noooste@users.noreply.github.com>
Date: Fri, 24 Apr 2026 12:09:04 +0200
Subject: [PATCH] docs: add garage setup guide and update config example
 filename

Signed-off-by: Noooste <83548733+Noooste@users.noreply.github.com>
---
 .gitignore                                 |  4 +-
 config.yaml.example => config.example.yaml |  0
 docs/garage-setup.md                       | 59 ++++++++++++++++++++++
 3 files changed, 61 insertions(+), 2 deletions(-)
 rename config.yaml.example => config.example.yaml (100%)
 create mode 100644 docs/garage-setup.md

diff --git a/.gitignore b/.gitignore
index 2534c22..c724da5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -52,7 +52,7 @@ dist-ssr
 *.sw?
 
 .env*
-!config.yaml.example
+!config.example.yaml
 docker-compose.*.yml
 !backend/tests/smoke/docker-compose.test.yml
 
@@ -64,6 +64,6 @@ garage.toml
 backend/docs/
 config.yaml
 docs/**/*.md
-
+!docs/garage-setup.md
 # Superpowers brainstorm / session scratch
 .superpowers/
\ No newline at end of file
diff --git a/config.yaml.example b/config.example.yaml
similarity index 100%
rename from config.yaml.example
rename to config.example.yaml
diff --git a/docs/garage-setup.md b/docs/garage-setup.md
new file mode 100644
index 0000000..49e47e1
--- /dev/null
+++ b/docs/garage-setup.md
@@ -0,0 +1,59 @@
+# Setting Up a Garage Cluster
+
+This guide walks you through setting up a local Garage cluster using Docker Compose for use with Garage UI.
+
+If you already have a running Garage cluster, skip this and go straight to the [Quick Start](../README.md#quick-start).
+
+## Prerequisites
+
+- Docker & Docker Compose
+
+## 1. Start Garage
+
+From the garage-ui repository root:
+
+```bash
+docker compose up -d garage
+sleep 10
+```
+
+## 2. Initialize the Cluster Layout
+
+```bash
+# Assign the node to a zone with 1GB capacity
+docker compose exec garage garage layout assign -z dc1 -c 1G $(docker compose exec garage garage node id -q)
+
+# Apply the layout
+docker compose exec garage garage layout apply --version 1
+```
+
+## 3. Create an Admin Key
+
+```bash
+docker compose exec garage garage key create admin-key
+```
+
+Save the **access key** and **secret key** from the output — you'll need them for configuration.
+
+## 4. Configure Garage UI
+
+Copy the example config and fill in your Garage endpoints and admin token:
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+The `admin_token` can be found in your `garage.toml` file. See [Garage Configuration](../README.md#garage-configuration) for the required `garage.toml` settings.
+
+## 5. Start Garage UI
+
+```bash
+docker compose up -d garage-ui
+```
+
+Access Garage UI at http://localhost:8080
+
+## Next Steps
+
+- [Configuration reference](../config.example.yaml) for all available options
+- [Garage official documentation](https://garagehq.deuxfleurs.fr/documentation/) for advanced Garage setup
\ No newline at end of file