WebUI for Garage S3 Server

Garage WebUI is a simple admin web interface for Garage, a self-hosted, S3-compatible, distributed object storage service. This tool provides a convenient graphical interface for managing Garage clusters, buckets, access keys, and objects.

---

Key Features:

• Garage health status monitoring
• Cluster and layout management
• Create, update, and view bucket information
• Integrated objects/bucket browser
• Create and assign access keys

Links:

• Project GitHub: https://github.com/khairul169/garage-webui
• Garage Documentation: https://garagehq.deuxfleurs.fr/
• Garage Repository: https://git.deuxfleurs.fr/Deuxfleurs/garage

Prerequisites

Before installation, make sure you have:

• Installed and configured Garage server (minimum version 2.0.0)
• Admin API enabled in Garage configuration
• Required ports open (default 3909 for WebUI)
• Access to the garage.toml configuration file

Installation via Docker Compose

If you use Docker for Garage, it’s most convenient to install WebUI alongside Garage using Docker Compose.

Create a docker-compose.yml file:

services:
  garage:
    image: dxflrs/garage:v2.0.0
    container_name: garage
    volumes:
      - ./garage.toml:/etc/garage.toml
      - ./meta:/var/lib/garage/meta
      - ./data:/var/lib/garage/data
    restart: unless-stopped
    ports:
      - 3900:3900  # S3 API
      - 3901:3901  # RPC
      - 3902:3902  # S3 Web
      - 3903:3903  # Admin API

  webui:
    image: khairul169/garage-webui:latest
    container_name: garage-webui
    restart: unless-stopped
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
    ports:
      - 3909:3909
    environment:
      API_BASE_URL: "http://garage:3903"
      S3_ENDPOINT_URL: "http://garage:3900"

Start the containers:

docker-compose up -d

Garage Configuration Setup

Garage WebUI uses values from the Garage configuration file. Make sure your garage.toml file contains the required parameters:

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
metadata_auto_snapshot_interval = "6h"

replication_factor = 3
compression_level = 2

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "localhost:3901"  # Required!
rpc_secret = "YOUR_RPC_SECRET_HERE"

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

[s3_web]  # Optional, for bucket web hosting
bind_addr = "[::]:3902"
root_domain = ".web.domain.com"
index = "index.html"

[admin]  # Required!
api_bind_addr = "[::]:3903"
admin_token = "YOUR_ADMIN_TOKEN_HERE"
metrics_token = "YOUR_METRICS_TOKEN_HERE"

Important parameters:

• rpc_public_addr — must be specified
• [admin] section — required for WebUI to work
• admin_token — used for authentication

Environment Variables

WebUI supports the following environment variables for configuration:

Variable	Description	Default
CONFIG_PATH	Path to Garage configuration file	/etc/garage.toml
BASE_PATH	Base path or prefix for WebUI	–
API_BASE_URL	Garage Admin API URL	From configuration
API_ADMIN_KEY	Admin API key	From configuration
S3_REGION	S3 Region	From configuration
S3_ENDPOINT_URL	S3 endpoint URL	From configuration
PORT	Port for WebUI	3909

If WebUI cannot load parameters from configuration, you can set them manually via environment variables.

Authentication Setup

By default, WebUI does not require authentication. To enable basic authentication, use the AUTH_USER_PASS environment variable.

Generating Password Hash

Create a username and password hash using the htpasswd utility:

htpasswd -nbBC 10 "YOUR_USERNAME" "YOUR_PASSWORD"

If the htpasswd command is not found, install the apache2-utils package:

# Debian/Ubuntu
sudo apt install apache2-utils

# RHEL/CentOS
sudo yum install httpd-tools

Applying Authentication

Add the environment variable to the webui section in docker-compose.yml:

webui:
  image: khairul169/garage-webui:latest
  environment:
    AUTH_USER_PASS: "username:$2y$10$DSTi9o..."
    API_BASE_URL: "http://garage:3903"
    S3_ENDPOINT_URL: "http://garage:3900"

After making changes, restart the containers:

docker-compose down
docker-compose up -d

Reverse Proxy Setup (Nginx)

It’s recommended to place WebUI behind a reverse proxy server for SSL/TLS protection.

Nginx Configuration Example

server {
    listen 80;
    server_name garage-ui.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name garage-ui.example.com;

    ssl_certificate /etc/letsencrypt/live/garage-ui.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/garage-ui.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3909;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

After configuration, restart Nginx:

sudo systemctl restart nginx

Using WebUI

After successful installation, open a web browser and navigate to:

• http://your-ip:3909 (without proxy)
• https://garage-ui.example.com (with proxy)

In the interface you will be able to:

• View Garage cluster status
• Manage topology and nodes
• Create and configure buckets
• View and upload objects
• Manage access keys
• Assign access permissions

Troubleshooting

WebUI Not Loading

Problem: Data is not loading in the interface.

Solutions:

• Make sure you’re using the latest version of Garage (minimum 2.0.0)
• Check that Admin API is enabled in Garage configuration
• Ensure port 3903 (Admin API) is accessible
• Check logs: docker logs garage-webui

Admin API Connection Error

Problem: WebUI cannot connect to Garage Admin API.

Solutions:

• Check that admin.api_bind_addr parameter is specified in garage.toml
• Ensure admin_token is correct
• For Docker, verify containers are on the same network
• Try setting API_BASE_URL and API_ADMIN_KEY manually

Ports Busy

Problem: Port 3909 is already in use.

Solution: Change the port in docker-compose.yml:

webui:
  image: khairul169/garage-webui:latest
  environment:
    PORT: 8080
  ports:
    - 8080:8080

After making changes, restart the container:

docker-compose up -d webui

Security

Security Recommendations:

• Always enable authentication in production
• Use HTTPS via reverse proxy
• Limit WebUI access by IP addresses via firewall
• Regularly update Garage and WebUI to latest versions
• Don’t publish tokens and secrets in public repositories
• Use strong passwords for admin_token

Updating

To update to the latest version:

# Pull the latest image version
docker-compose pull webui

# Recreate the container
docker-compose up -d webui

Or update all services at once:

docker-compose pull
docker-compose down
docker-compose up -d

Development

If you want to build the project yourself or add new features:

# Clone the repository
git clone https://github.com/khairul169/garage-webui.git
cd garage-webui

# Install dependencies
pnpm install
cd backend && pnpm install && cd ..

# Run in development mode
pnpm run dev  # Runs client and server simultaneously

# Or run separately
pnpm run dev:client  # Client side
cd backend && pnpm run dev:server  # Server side

Technologies:

• Frontend: TypeScript + React
• Backend: Go

Useful Links

• Official Garage Documentation: https://garagehq.deuxfleurs.fr/documentation/
• GitHub Garage WebUI: https://github.com/khairul169/garage-webui
• Garage Quick Start: https://garagehq.deuxfleurs.fr/documentation/quick-start/
• Issues and Support: https://github.com/khairul169/garage-webui/issues

Conclusion

Garage WebUI provides a convenient graphical interface for managing S3-compatible Garage storage. Thanks to simple installation via Docker Compose, you can quickly deploy the web interface and start managing your cluster through a browser.