btool

Backup orchestration control plane with a web dashboard for server onboarding, backup visibility, restore operations, and connectivity verification.

What this project provides

• Fastify API for managing backup servers and schedules
• Web UI at /dashboard for day-to-day operations
• Encrypted secret storage for SSH and cloud credentials
• Restore snapshot browsing + restore trigger flow
• Server connectivity test endpoint and UI action

Tech stack

• Node.js + TypeScript
• Fastify
• Prisma + PostgreSQL
• SSH transport via ssh2

Prerequisites

• Node.js 20+
• npm
• Docker (for local PostgreSQL)

Environment setup

Copy env template:

cp .env.example .env

Required environment variables:

• DATABASE_URL (PostgreSQL connection)
• ORCHESTRATOR_ENCRYPTION_KEY (base64-encoded 32-byte key)
• ORCHESTRATOR_ENCRYPTION_KEY_VERSION (e.g., v1)

Generate a key (example):

openssl rand -base64 32

Local development

Start PostgreSQL:

docker run -d --name btool-postgres \
	-e POSTGRES_USER=postgres \
	-e POSTGRES_PASSWORD=postgres \
	-e POSTGRES_DB=btool \
	-p 5432:5432 postgres:16

Install dependencies:

npm install

Generate Prisma client:

npm run prisma:generate

Run API + dashboard:

npm run dev

Default server address: http://localhost:3000

Main routes

• GET /health
• GET /dashboard

Server management:

• POST /servers
• POST /servers/:serverId/cloud-credentials
• PUT /servers/:serverId/source-directories
• PUT /servers/:serverId/schedule
• PUT /servers/:serverId/retention-policy
• GET /servers/status
• POST /servers/:serverId/connectivity-test

Backup/restore observability:

• GET /servers/:serverId/backups/history
• GET /servers/:serverId/backups/history/:attemptId/log
• GET /servers/:serverId/restores/snapshots
• POST /servers/:serverId/restores
• GET /servers/:serverId/restores/history
• GET /servers/:serverId/restores/history/:attemptId/log
• GET /servers/:serverId/retention/prune-logs

Testing

Run all tests:

npm test

Run a focused test file:

npm run test -- src/modules/dashboard/dashboard.route.spec.ts

Security notes

• Secrets are encrypted before persistence.
• Keep .env out of source control.
• Rotate encryption key versions using ORCHESTRATOR_ENCRYPTION_KEY_VERSION.
• Use the connectivity test in the dashboard to validate SSH configuration before scheduling backups.

Git hygiene

The root .gitignore is configured to exclude sensitive files and common local artifacts, including:

• .env and .env.* (except .env.example)
• private keys/certs (*.pem, *.key, etc.)
• local DB and dump files (*.db, *.sqlite, *.sql, *.dump)
• logs/build outputs (dist/, *.log, etc.)