Dockstash 0.1.0

Dockstash is open-source, self-hostable backup orchestration for Docker — encrypted restic snapshots on storage you own, a pull-based agent fleet, schedules, restore drills, health monitoring and alerting.

This is the first tagged release, licensed AGPL-3.0-only.

What it does

Point it at a project and it detects and captures four layers:

• Files — volumes, bind mounts, anything under an allowed root
• Databases — Postgres, MySQL/MariaDB, MongoDB, Redis/Valkey, SQLite, ClickHouse, Elasticsearch, RabbitMQ, MinIO, InfluxDB, Neo4j — dumped through each engine's own tooling and streamed straight into restic, never staged on the container's disk
• Proxy configuration — the nginx/Caddy config that makes the stack reachable
• Compose metadata — what you need to stand the project back up

Then:

Encrypted restic repositories	Deduplicated, incremental, on your own storage target over SSH
Schedules	Any cron cadence, per project, with retention policies you set
Restore drills	Automated verification that restores a snapshot into scratch space and diffs it — so "the backup ran" and "the backup works" stop being the same claim
Point-in-time restore	Resolve the newest snapshot at or before a timestamp, then restore it
Fleet agents	A daemon on each remote VPS, pulling work outbound-only — the control plane never opens a connection to your servers
Health + alerting	Per-project rollups, heartbeat detection for backups that quietly stopped, email and webhook channels
Live job logs	Streamed over Socket.IO while a job runs
Self-backup	Dockstash backs up its own database, so the recovery tool is itself recoverable

Seven UI locales (en, ar, fr, de, es, ru, zh) with RTL support.

Getting started

git clone https://github.com/SelmiAbderrahim/dockstash.git && cd dockstash
cp .env.example .env
for v in MASTER_ENCRYPTION_KEY JWT_SECRET SESSION_SECRET; do
  echo "$v=$(openssl rand -hex 32)"
done   # paste each into .env
docker compose up -d --build

Open http://127.0.0.1:3000 and register. There is no seeder and no bootstrap password — the first account is just an account.

Full walkthrough, reverse-proxy config, and troubleshooting: docs/self-hosting.md.

Warning

Back up MASTER_ENCRYPTION_KEY outside this install. It wraps every secret Dockstash stores, including the passwords to the restic repositories holding your backups. Lose it and none of it is recoverable.

Publishing the agent image

Dockstash ships no prebuilt agent image and no registry account — every install publishes its own, so nothing you run on your VPSes was pushed by a third party.

NS=your-dockerhub-user
docker login -u "$NS"
docker buildx build --platform linux/amd64,linux/arm64 -t "$NS/agent:latest" --push agent/

Then set VITE_AGENT_IMAGE=your-dockerhub-user/agent:latest in .env and rebuild web. Details in docs/fleet-agents.en.md.

Architecture

Three independent npm packages, no monorepo tooling:

client/   React 19 · Vite · Redux Toolkit · Tailwind v4 · shadcn/ui
server/   Express 4 · Mongoose 8 · Passport · Socket.IO · zod 4
agent/    The VPS daemon — pull-based worker, outbound-only

The control plane runs as a Compose stack: api, web, mongo, redis, and a least-privilege docker-socket-proxy. The api reaches Docker only through that proxy — it never bind-mounts the raw socket. Every persisted secret is an AES-256-GCM envelope. Node 24 LTS throughout.

CI gates every merge on typecheck, lint, 100% coverage across all four dimensions on all three packages, and npm audit --audit-level=high.

What this is not

• No billing code, no usage caps, no plan or tier
• No telemetry, no phone-home, no analytics
• No platform-operator role — the ladder tops out at Admin

A note on versioning

Versioning restarts at 0.1.0. The 2.0.0 on client/server and 0.4.0 on agent were inherited from the MERN starter this repository was forked from and never described a Dockstash release.

License

AGPL-3.0-only. If you run a modified version as a network service, §13 requires you to offer your users the modified source — the app footer carries that link, configurable via VITE_SOURCE_URL.

A separate commercial license is available for organizations that cannot use AGPL software: support@dockstash.com.