Database backups. One workspace. Your infrastructure.
Self-hosted backup management with a .NET 10 API and React / TypeScript frontend.
Quick start · Usage · Documentation · Roadmap · Polski
Manage database connections, access, scheduled exports and backup history from one responsive dashboard. Manual and scheduled backups share a persistent queue with cancellation, duplicate prevention and visible results.
| Database | Backup format | Requirements |
|---|---|---|
| MySQL / MariaDB | SQL dump in ZIP | Compatible dump client and export grants |
| PostgreSQL | SQL dump in ZIP | pg_dump at least as new as the source major |
| SQL Server | Native .bak |
Dedicated staging filesystem shared with the API |
| SQLite | Online .sqlite snapshot |
Approved local source mount |
Optional global or individual passwords encrypt new backups. Authorized users can download files and request saved restore-test previews when the deployment runtime is enabled. A preview samples restored data; it does not prove a complete disaster recovery.
Run all commands from the repository root. Docker deployments require Docker Engine with Compose/Buildx and Node.js for the initialization helper. Source development also requires the .NET 10 SDK selected by global.json and Node.js 22.12+.
node scripts/dev.mjs init
docker compose up --build -d --waitThe private .env contains ADMIN_EMAIL, ADMIN_PASSWORD and a stable CRYPTO_KEY. Initialization preserves existing secrets. Add your public hostname to ALLOWED_HOSTS before starting, keeping
localhost;127.0.0.1 for the container health probe. For example:
ALLOWED_HOSTS=backups.example.com;localhost;127.0.0.1.
One production file, compose.yaml, includes Docker restore testing by default.
Initialization detects RESTORE_DOCKER_GID from the local socket and creates the
editable config/appsettings.Runtime.json. When preparing on another machine,
set the group ID from stat -c %g /var/run/docker.sock on the deployment host.
The restore-images service preloads all configured engine images before API
startup; the first run can download several GB. Docker socket access grants daemon
control, so deploy on a dedicated host/VM. Restore runtime.
Older Docker hosts may require a temporary API-version override; see that guide.
Point your HTTPS reverse proxy at http://127.0.0.1:8080 and enable WebSocket forwarding. Open your public HTTPS URL to sign in. Both application containers use HTTP internally; neither needs a certificate. The API stays private. Production cookies require HTTPS in the browser.
For isolated private HTTP testing, set ALLOW_INSECURE_HTTP=true in .env,
recreate the API, then open http://<host>:<FRONTEND_PORT>. This explicitly removes
Secure from session/CSRF cookies; keep it false for public HTTPS deployments.
CSRF validation remains required in both modes. Login troubleshooting.
FRONTEND_PORT changes the host upstream port; existing .env files keep their previous value. If your proxy runs in Docker, attach it to the frontend network and use frontend:8080; see the deployment guide.
node scripts/dev.mjs init
dotnet restore OctoBackup.sln
npm ci --prefix Frontend
node scripts/dev.mjsOpen http://127.0.0.1:5173. The API runs on http://127.0.0.1:5080. Use node scripts/dev.mjs api or node scripts/dev.mjs frontend for separate terminals. Host-run exports require local dump tools.
For API-only development, dotnet run --project Backend/src/Server.Api creates private development settings on first startup. Initial credentials are in the ignored appsettings.Local.json; existing accounts are preserved.
Optional local database targets:
docker compose -f compose.dbs.yaml up -d --waitThese are backup targets; OctoBackup itself stores metadata in SQLite.
Both Dockerfiles use the repository root as build context:
docker build -f Backend/Dockerfile -t lewan24/octobackup-api:latest .
docker build -f Frontend/Dockerfile -t lewan24/octobackup-web:latest .
docker compose up -d --waitTo publish the locally built tags:
docker login
docker push lewan24/octobackup-api:latest
docker push lewan24/octobackup-web:latestUse your registry names consistently in build commands and API_IMAGE / WEB_IMAGE
when publishing under another account.
The images are Linux containers. Run them with Docker Engine on Linux or
Docker Desktop in Linux-container mode on Windows.
The selected Docker daemon determines the CPU architecture; publishing does not
create a multi-architecture manifest. Native Windows-container mode is unsupported.
Compose builds both application images from source by default. For previously
pulled images, use docker compose up --no-build --pull never -d --wait.
For a console publish and frontend bundle:
dotnet publish Backend/src/Server.Api -c Release -o Backend/artifacts/publish
npm run build --prefix FrontendA 401 from POST /api/auth/Login means the credentials/account were rejected;
a session-expired message applies to protected requests after login. Check the
API's Sign-in rejected reason and login troubleshooting.
Bootstrap values create the first account only; changing them does not reset a
password in an existing volume.
- Sign in as administrator. In Application settings, approve the exact database/SSH hostnames or IPs your deployment may contact. Review registration and account confirmation policies.
- In Servers, create a connection and test it. Assign operators access where needed. Database TLS and verified SSH fingerprints are independent of the web reverse proxy.
- Choose an individual backup password or enable global encryption in Application settings. Encryption starts disabled; keep recovery passwords outside the application.
- Select Queue backup, or create a schedule. Follow the queue until it succeeds; acceptance is not completion. One export runs at a time.
- Open Backup history to download an archive or choose Test / preview. The production stack enables Docker restore tests and prepares compatible engine images automatically.
Keep the complete /data volume, Data Protection keys and external CRYPTO_KEY in your recovery plan. Use one API replica per data directory. SQL Server needs shared staging; SQLite needs a narrow source mount. Backup and recovery details.
flowchart LR
Browser -->|HTTPS| Proxy[Your reverse proxy]
Proxy -->|HTTP / WebSocket| Web[React + Nginx :8080]
Web -->|HTTP / scoped events| API[.NET API :8080]
API --> Data[(SQLite metadata / backups / keys)]
API --> Sources[(Database targets / SSH)]
API --> Tests[Isolated restore containers]
| Path | Contents |
|---|---|
Backend/ |
API, modules, tests, recovery tool and Dockerfile |
Frontend/ |
React features, Nginx proxy, tests and Dockerfile |
deploy/ |
Optional provider network and SQL Server staging examples |
scripts/ |
Development launcher, deployment tests and disposable smoke checks |
docs/ |
Focused reference guides and editable architecture diagrams |
Run backend checks before browser tests; Windows can lock running API binaries.
dotnet build OctoBackup.sln
dotnet test Backend/tests/OctoBackup.Tests
npm test --prefix Frontend
npm run build --prefix Frontend
node --test scripts/deployment.test.mjs
node Frontend/node_modules/@playwright/test/cli.js install chromium
npm run test:e2e --prefix Frontend
npm audit --prefix Frontend
dotnet list OctoBackup.sln package --vulnerable --include-transitiveTests and deployment smoke checks use disposable data. Instructions for container and provider checks are in operations.
| Guide | What you will find |
|---|---|
| Operations | Deployment, reverse proxy, configuration reload, development and checks |
| Database connections | Dump clients, grants, networking and SQL Server staging |
| Backups and recovery | Encryption, source mounts, restore testing and offline decryption |
| Architecture | Modules, data flow, queue contracts and editable draw.io diagrams |
| Security | Trust boundaries, access controls and operational limits |
| Interface | UI tokens, interaction patterns and accessibility |
Suggestions for future work, rather than available features:
- Separate restore execution from the web API into a dedicated worker.
- Add MFA, verified email changes, invitations and password recovery.
- Add backup checksums, manifests, orphan-file reconciliation and configurable retries.
- Extend retention editing, server-side history filtering and timezone/DST scheduling.
- Provide an offline credential rekey tool and external key wrapping.
- Add object-storage destinations, remote SQLite transport and SQL Server retrieval adapters.
- Expand engine/version/large-schema restore coverage and accessibility CI.
- Generate API documentation and browser types; add English/Polish UI localization.