gsadmin/garage-ui
1
0
Fork 0
mirror of https://github.com/Noooste/garage-ui.git synced 2026-08-28 07:57:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README to enhance clarity and modernize presentation

Browse Source 
Signed-off-by: Noooste <83548733+Noooste@users.noreply.github.com>
This commit is contained in:
Noooste
2026-04-24 11:08:55 +02:00
parent 21f10a0274
commit b90e4f71be
1 changed files with 60 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+60 -107
View File
@@ -1,13 +1,15 @@
# Garage UI <p align="center">
<a href="https://github.com/Noooste/garage-ui/actions/workflows/build.yml"><img src="https://github.com/Noooste/garage-ui/actions/workflows/build.yml/badge.svg" alt="Docker Build" /></a>
<a href="https://github.com/Noooste/garage-ui/actions/workflows/release.yml"><img src="https://github.com/Noooste/garage-ui/actions/workflows/release.yml/badge.svg" alt="Helm Chart" /></a>
<a href="https://codecov.io/gh/Noooste/garage-ui"><img src="https://codecov.io/gh/Noooste/garage-ui/branch/main/graph/badge.svg" alt="Coverage" /></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
<a href="https://go.dev/"><img src="https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go" alt="Go Version" /></a>
<a href="https://artifacthub.io/packages/search?repo=garage-ui"><img src="https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/garage-ui" alt="Artifact Hub" /></a>
</p>
A web interface for managing [Garage](https://garagehq.deuxfleurs.fr/) object storage clusters. # Garage UI — Web Dashboard for Garage S3 Storage
[![Docker Build](https://github.com/Noooste/garage-ui/actions/workflows/build.yml/badge.svg)](https://github.com/Noooste/garage-ui/actions/workflows/build.yml) A modern web interface to manage <a href="https://garagehq.deuxfleurs.fr/">Garage</a> object storage clusters. Browse buckets, manage access keys, monitor your cluster, all from your browser.
[![Helm Chart](https://github.com/Noooste/garage-ui/actions/workflows/release.yml/badge.svg)](https://github.com/Noooste/garage-ui/actions/workflows/release.yml)
[![Coverage](https://codecov.io/gh/Noooste/garage-ui/branch/main/graph/badge.svg)](https://codecov.io/gh/Noooste/garage-ui)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go Version](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go)](https://go.dev/)
[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/garage-ui)](https://artifacthub.io/packages/search?repo=garage-ui)
--- ---
@@ -24,69 +26,30 @@ A web interface for managing [Garage](https://garagehq.deuxfleurs.fr/) object st
## Features ## Features
- Bucket and object management - **Bucket management** — create, configure, and browse buckets with drag-and-drop file uploads
- User access control - **Access key management** — create keys, assign per-bucket permissions
- Cluster monitoring - **Cluster overview** — monitor node status, layout configuration, and storage usage
- Multiple authentication options (none/basic/OIDC) - **Flexible authentication** — no auth, basic credentials, or OIDC (Keycloak, Authentik, etc.)
- Drag-and-drop file uploads - **Easy deployment** — single Docker image or Helm chart, configure with one YAML file
## Compatibility
Garage UI auto-detects your Garage version at startup. Most features work across all supported versions.
| Feature | Garage v1.x | Garage v2.x |
|---|---|---|
| Bucket management | Yes | Yes |
| Object browser | Yes | Yes |
| Key management | Yes | Yes |
| Access control | Yes | Yes |
| Cluster health | Yes | Yes |
| Cluster statistics | — | Yes |
| Per-node details | Limited | Yes |
Features unavailable on your version appear as disabled in the interface.
## Quick Start ## Quick Start
### Prerequisites ### Prerequisites
- Docker & Docker Compose - Docker & Docker Compose
- Garage S3 cluster (v1.1.0+) or use the included setup - A running Garage cluster (v2.1.0+) — [setup guide](docs/garage-setup.md) if you need one
### 1. Clone & Setup ### 1. Clone & Configure
```bash ```bash
git clone https://github.com/Noooste/garage-ui.git git clone https://github.com/Noooste/garage-ui.git
cd garage-ui cd garage-ui
``` cp config.example.yaml config.yaml
### 2. Start Garage
If you don't have Garage running:
```bash
docker compose up -d garage
sleep 10
# Initialize cluster
docker compose exec garage garage layout assign -z dc1 -c 1G $(docker compose exec garage garage node id -q)
docker compose exec garage garage layout apply --version 1
# Create admin key
docker compose exec garage garage key create admin-key
```
Save the access key and secret key from the output.
### 3. Configure
```bash
cp config.yaml.example config.yaml
``` ```
Edit `config.yaml` with your Garage endpoints and admin token (from `garage.toml`). Edit `config.yaml` with your Garage endpoints and admin token (from `garage.toml`).
### 4. Start UI ### 2. Start
```bash ```bash
docker compose up -d garage-ui docker compose up -d garage-ui
@@ -94,43 +57,6 @@ docker compose up -d garage-ui
Access at http://localhost:8080 Access at http://localhost:8080
## Configuration
Minimum required config:
```yaml
server:
port: 8080
garage:
endpoint: "http://garage:3900"
admin_endpoint: "http://garage:3903"
admin_token: "your-admin-token"
region: "garage"
```
Enable authentication (optional):
```yaml
auth:
admin:
enabled: true
username: "admin"
password: "your-password"
```
See [config.yaml.example](config.yaml.example) for all options.
### Environment Variables
Override any config value with `GARAGE_UI_` prefix:
```bash
GARAGE_UI_SERVER_PORT=8080
GARAGE_UI_GARAGE_ENDPOINT=http://garage:3900
GARAGE_UI_GARAGE_ADMIN_TOKEN=your-token
```
## Deployment ## Deployment
### Docker ### Docker
@@ -151,22 +77,32 @@ helm install garage-ui garage-ui/garage-ui \
--set garage.adminToken=your-token --set garage.adminToken=your-token
``` ```
## Development ## Configuration
Backend (Go 1.25+): Minimum required config:
```bash
cd backend ```yaml
go run main.go --config ../config.yaml server:
port: 8080
garage:
endpoint: "http://garage:3900"
admin_endpoint: "http://garage:3903"
admin_token: "your-admin-token"
region: "garage"
``` ```
Frontend (Node.js 25+): See [config.example.yaml](config.example.yaml) for all options including authentication, CORS, and logging.
```bash
cd frontend
npm install
npm run dev
```
API docs: http://localhost:8080/api/v1/ ### Environment Variables
Override any config value with `GARAGE_UI_` prefix:
```bash
GARAGE_UI_SERVER_PORT=8080
GARAGE_UI_GARAGE_ENDPOINT=http://garage:3900
GARAGE_UI_GARAGE_ADMIN_TOKEN=your-token
```
## Garage Configuration ## Garage Configuration
@@ -188,6 +124,23 @@ api_bind_addr = "[::]:3900" # Default: 127.0.0.1:3900
For complete Garage configuration, see the [official documentation](https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/). For complete Garage configuration, see the [official documentation](https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/).
## Development
Backend (Go 1.25+):
```bash
cd backend
go run main.go --config ../config.yaml
```
Frontend (Node.js 25+):
```bash
cd frontend
npm install
npm run dev
```
API docs: http://localhost:8080/api/v1/
## Troubleshooting ## Troubleshooting
**Connection failed:** **Connection failed:**
@@ -226,7 +179,7 @@ Ideas being considered. Contributions welcome.
- [ ] Per-bucket usage graph over time - [ ] Per-bucket usage graph over time
**Access keys** **Access keys**
- [ ] Permission matrix view (keys × buckets) - [ ] Permission matrix view (keys x buckets)
- [ ] Key rotation helper - [ ] Key rotation helper
- [ ] Copy-ready snippets per key (aws-cli, rclone, restic, s3cmd, mc, Terraform) - [ ] Copy-ready snippets per key (aws-cli, rclone, restic, s3cmd, mc, Terraform)
@@ -256,4 +209,4 @@ MIT - see [LICENSE](LICENSE)
- [Issues](https://github.com/Noooste/garage-ui/issues) - [Issues](https://github.com/Noooste/garage-ui/issues)
- [Contributing](CONTRIBUTING.md) - [Contributing](CONTRIBUTING.md)
- [Garage Docs](https://garagehq.deuxfleurs.fr/documentation/) - [Garage Docs](https://garagehq.deuxfleurs.fr/documentation/)