Restic Explorer

A lightweight monitoring interface for restic backup repositories, built to feed status and health data into observability solutions such as Grafana, Prometheus, or Uptime Kuma. It includes its own dashboard UI for browsing repositories and snapshots, but its primary purpose is to expose reliable, queryable backup health signals to external monitoring systems. Built with Spring Boot 4, Thymeleaf, and Bootstrap 5.

Key Features

• Observability-First Health Signals — /actuator/health exposes per-repository scan, integrity-check, and retention status for easy integration with Grafana, Prometheus, Uptime Kuma, or any HTTP-monitoring tool
• Multi-Repository Dashboard — browse all your restic repos in one place with status badges, groups, and lock warnings
• Automated Scanning & Integrity Checks — scheduled restic snapshots and restic check --read-data
• Retention Policies — advisory daily/weekly/monthly/yearly rules with amber violation warnings
• Encrypted Credentials — AES-256-GCM at rest for passwords and backend keys
• Dark Mode & Responsive UI — Bootstrap 5.3 with automatic light/dark theme

Supported Backends

Backend	URL Format	Details
Amazon S3 / S3-Compatible	s3:https://s3.amazonaws.com/bucket/path	Access Key, Secret Key, Region
Azure Blob Storage	azure:container:/path	Account Name, Account Key
SFTP	sftp:user@host:/path	Key-based auth only (tutorial)
REST Server	rest:http://host:8000/	Optional HTTP basic auth (tutorial)
Rclone	rclone:remote:path	Any rclone-supported backend (tutorial)

Quick Start

Docker Compose (recommended)

docker compose up --build -d

Open http://localhost:8080 and create the admin account on first launch.

Docker Hub

docker pull tmseidel/restic-explorer:latest

See Configuration → Docker Hub Image for a full docker-compose.yml.

Local Development

mvn spring-boot:run       # Start with H2 file DB
mvn test                  # Run tests (H2 in-memory)
mvn clean package         # Build jar

Requires Java 21+ and restic on PATH.

Querying Backup Health

The main integration point is GET /actuator/health. It returns the overall application status and a resticMetadata object with per-repository scan, check, and retention information.

Basic curl checks

# Overall status (HTTP 200 when healthy, non-200 when any repo failed)
curl -fsS http://localhost:8080/actuator/health | jq .

# Number of healthy vs unhealthy repositories
curl -fsS http://localhost:8080/actuator/health | jq '.components.resticMetadata.details | {healthy: .healthyRepositories, unhealthy: .unhealthyRepositories}'

# Per-repo status for a repository named "nas-backup"
curl -fsS http://localhost:8080/actuator/health | jq '.components.resticMetadata.details."repository_nas-backup"'

Common jq filters

# List every repository and its last scan/check status
curl -fsS http://localhost:8080/actuator/health | jq '.components.resticMetadata.details | to_entries[] | select(.key | startswith("repository_")) | {name: .key, scan: .value.lastScanStatus, check: .value.lastCheckStatus, retentionOK: .value.retentionPolicyFulfilled}'

# Show only repositories with scan or check failures
curl -fsS http://localhost:8080/actuator/health | jq '.components.resticMetadata.details | to_entries[] | select(.key | startswith("repository_")) | select(.value.lastScanStatus == "FAILED" or .value.lastCheckStatus == "FAILED")'

# Count total repositories and cached snapshots
curl -fsS http://localhost:8080/actuator/health | jq '.components.resticMetadata.details | {repos: .totalRepositories, snapshots: .totalCachedSnapshots}'

Integrations

• Uptime Kuma / simple HTTP monitor — monitor http://localhost:8080/actuator/health. The endpoint returns HTTP 503 when any repository scan or integrity check has failed.
• Prometheus — scrape /actuator/prometheus (if enabled) or use the JSON exporter against /actuator/health to turn healthyRepositories / unhealthyRepositories into metrics.
• Grafana — use the Infinity or JSON API datasource to query /actuator/health and build per-repo health panels.

See Configuration for enabling /actuator/prometheus and securing actuator access.

Screenshots

Dashboard	Snapshots	Snapshot Detail

Documentation

Document	Description
User Guide	Setup, adding repositories, browsing snapshots, retention policies
Configuration	Properties, Docker env vars, encryption, deployment, migration
Architecture	System design, data model, extensibility, technology stack
SFTP Testing	SFTP backend setup tutorial
REST Server Testing	REST server backend setup tutorial
Rclone Testing	Rclone backend setup tutorial
Contributing	How to contribute
Code of Conduct	Community guidelines

License

MIT — © 2026 Tom Seidel