Kuraban

Kuraban (蔵番) is Japanese for the keeper of a storehouse: the one who guards what is stored and decides who gets in. It is a web interface for Garage, the S3-compatible distributed object storage. It manages buckets, objects and access keys, shows cluster state, and keeps its own metrics history, so you don't need a separate Prometheus and Grafana stack.

Features

• Buckets and objects. Create and configure buckets, set quotas, website hosting, and global and local aliases, browse objects with prefix and recursive search, upload with drag and drop, preview, download and bulk-delete files and folders.
• Access keys. Create keys, edit a key's read, write and owner permissions across all buckets in one table, reveal secrets.
• Cluster. Node status, health, per-node statistics. Layout management: assign zones and capacity, preview the result, apply or discard, follow a migration and skip dead nodes.
• Dashboard. S3 traffic, latency percentiles, error rates, storage growth, disk usage, block I/O, resync and RPC metrics. History is stored in a local SQLite database with automatic 5-minute and hourly rollups.
• Multiple clusters. Add several Garage clusters and switch between them from the header.
• Authentication. Local admin account, login with the Garage admin token, or OIDC (Keycloak, Authentik, etc.).
• Team-based access control. Optional, for OIDC users. See docs/access-control.md.
• Runtime settings. Monitoring interval and retention, dashboard thresholds, log level and IP allowlists are changed in the UI without a restart.
• Interface. English and Russian, several color themes with light and dark variants, command palette (Ctrl+K).

Garage admin API v1 and v2 are both supported. Some cluster statistics are only available on v2.

Garage 2.5.0 or newer is recommended. Older versions work, but without its batch requests lists and metrics ask about each bucket and key separately, which gets slow at around a thousand of them.

Quick start

Try it with a bundled Garage

You need Docker with Compose v2 and Git.

git clone https://github.com/Mimic890/kuraban.git
cd kuraban
./demo/up.sh

The script generates secrets in demo/.env, starts a single-node Garage with Kuraban already connected to it, assigns the node a layout (zone dc1, capacity 1 GB), and prints the URL, username and password. You can create buckets right away. Running it again keeps the existing secrets, layout and data.

This setup is for evaluation only. Stop it with docker compose -f demo/compose.yml down. To start over, also delete demo/.env, demo/data, demo/garage/meta and demo/garage/data.

Use your own Garage

You need Docker with Compose v2 and a running Garage cluster. To set up a local one by hand, see docs/garage-setup.md.

1. Download the example Compose file:

   curl -o compose.yml https://raw.githubusercontent.com/Mimic890/kuraban/main/docker-compose.example.yml
   

2. Create the data directory and start the container:

   mkdir -p data
   printf 'UID=%s\nGID=%s\n' "$(id -u)" "$(id -g)" > .env
   docker compose up -d
   

3. Open http://127.0.0.1:8080 and create the admin account (password of at least 12 characters).

4. Add a cluster: enter the S3 endpoint (for example http://garage:3900), the admin endpoint (http://garage:3903) and the admin_token from your garage.toml.

Important

The first person to open the UI creates the admin account. Keep the port closed to the outside until setup is done, or provision the account up front with KURABAN_AUTH_ADMIN_USERNAME and KURABAN_AUTH_ADMIN_PASSWORD.

The example binds to 127.0.0.1 and runs in development mode. For a public deployment, put the UI behind a reverse proxy with HTTPS and set KURABAN_SERVER_ENVIRONMENT=production and KURABAN_SERVER_ROOT_URL=https://your-domain.

Configuration

The basics are set with environment variables:

Variable	Default	Description
KURABAN_SERVER_HOST	::	Listen address.
KURABAN_SERVER_PORT	8080	Listen port.
KURABAN_SERVER_ENVIRONMENT	production	production or development. Production enforces secure cookie and OIDC settings.
KURABAN_SERVER_ROOT_URL		External URL of the UI. Required for OIDC.
KURABAN_DATA_DIR	data	Persistent state directory (/app/data in Docker). Mount a volume here.
KURABAN_LOGGING_LEVEL	info	trace, debug, info, warn, error.

Everything else (first-run provisioning, OIDC, CORS, the /metrics endpoint, request limits, the YAML config file and secrets from files) is covered in docs/configuration.md.

Garage metrics

The S3, block and RPC charts read Garage's /metrics endpoint using the cluster admin token. If metrics_token in garage.toml differs from admin_token, make them equal or remove metrics_token. Cluster, disk and bucket charts work either way.

Documentation

• Configuration reference
• Local Garage cluster for testing
• Multi-user access control
• Architecture
• Contributing and development setup

Not planned

Garage admin tokens (Kuraban itself runs on one), PurgeBlocks (irreversible data loss), ImportKey, InspectObject, worker variables. Per-key/per-bucket request stats are not possible: Garage metrics only carry api_endpoint.

License

Copyright (C) 2026 Mimic890

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License, version 3. See LICENSE for the full text.