Garage Web UI

Download the appropriate binary for your architecture, make it executable, and move it to your system path.

$ wget -O garage-webui https://github.com/khairul169/garage-webui/releases/download/1.1.0/garage-webui-v1.1.0-linux-amd64
$ chmod +x garage-webui
$ sudo cp garage-webui /usr/local/bin

To run the binary with a specific configuration file:

$ CONFIG_PATH=./garage.toml garage-webui

$ wget -O garage-webui https://github.com/khairul169/garage-web-ui/releases/download/1.1.0/garage-webui-v1.1.0-linux-amd64
$ chmod +x garage-webui
$ sudo cp garage-webui /usr/local/bin

$ CONFIG_PATH=./garage.toml garage-webui

This project uses TypeScript/React for the UI and Go for the backend. To develop locally:

1. Clone the repository and install dependencies for the root and backend:

$ git clone https://github.com/khairul169/garage-webui.git
$ cd garage-webui && pnpm install
$ cd backend && pnpm install && cd ..

2. Run the development environment:

Option A: Run everything concurrently

$ pnpm run dev

Option B: Run client and server separately

$ pnpm run dev:client
$ cd backend
$ pnpm run dev:server

If you are running Garage in Docker, you can add the webui service to your docker-compose.yml. Ensure you provide the API_BASE_URL (pointing to the Garage admin API) and S3_ENDPOINT_URL (pointing to the S3 API) so the UI can communicate with the Garage container.

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
      - 3901:3901
      - 3902:3902
      - 3903:3903

  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"

To secure the Web UI, set the AUTH_USER_PASS environment variable using the format username:password_hash, where password_hash is a bcrypt hash of the password.

1. Generate the hash using htpasswd (requires apache2-utils):

htpasswd -nbBC 10 "YOUR_USERNAME" "YOUR_PASSWORD"

2. Add the resulting string to your environment configuration (e.g., in docker-compose.yml):

webui:
  environment:
    AUTH_USER_PASS: "username:$2y$10$DSTi9o..."

Run the Garage Web UI as a single Docker container. You must mount your existing garage.toml configuration file as a read-only volume so the UI can discover your Garage cluster settings.

$ docker run -p 3909:3909 -v ./garage.toml:/etc/garage.toml:ro --restart unless-stopped --name garage-webui khairul169/garage-webui:latest

The Garage Web UI uses specific types to represent the state of nodes and their roles within a cluster.

• Node: Represents a physical or virtual instance in the cluster. Key properties include id, addr (address), hostname, isUp (connectivity status), and lastSeenSecsAgo. It also tracks dataPartition and metadataPartition usage.
• Role: Defines the purpose and capacity of a node, including its zone, capacity, and associated tags.
• StagedRole: Represents a pending change to a node's role, specifically indicating if a role is marked for remove.
• DataPartition: Tracks storage usage with available and total numeric values.

The server uses a standard Go http.ServeMux with a specific routing hierarchy:

1. API Router: All API requests are handled by router.HandleApiRouter(). If BASE_PATH is configured, the API is prefixed with {BASE_PATH}/api.
2. UI Serving: Static files for the user interface are served via ui.ServeUI(mux).
3. Redirection: If BASE_PATH is non-empty, the root path / is permanently redirected to the BASE_PATH.
4. Session Management: The entire mux is wrapped in sessionMgr.LoadAndSave(mux), which provides session persistence and management middleware for all incoming requests.

You can deploy the Garage Web UI alongside a Garage instance using the provided docker-compose.yml. The setup includes a garage service and a webui service. The Web UI requires access to the garage.toml configuration file via a volume mount to function correctly.

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
      - 3901:3901
      - 3902:3903
      - 3903:3903

  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"

If the Web UI fails to load data, verify the following:

1. Garage Version: Ensure you are using the latest version of Garage.
2. Admin API: Confirm that your Garage instance has the admin API enabled.
3. Network Connectivity: Ensure the ports required for the admin API are accessible from the Web UI instance.

When configuring a bucket for website hosting, use the websiteConfig object. This requires setting websiteAccess (boolean) and optionally providing a websiteConfig object containing indexDocument and errorDocument paths.

{
  "websiteAccess": true,
  "websiteConfig": {
    "indexDocument": "index.html",
    "errorDocument": "404.html"
  }
}

The S3API configuration object defines the region, the network address where the S3 API is bound, and the root domain used for S3 requests.

export type S3API = {
  s3_region: string;
  api_bind_addr: string;
  root_domain: string;
};

Bucket quotas allow you to limit resource usage. The configuration requires an enabled boolean. If enabled, you can optionally set maxObjects and maxSize (both are coerced to numbers).

{
  "enabled": true,
  "maxObjects": 1000,
  "maxSize": 536870912
}