To back up self-hosted project management properly, you need three things: an archive of the database, a copy of the uploaded files, and proof that you can restore both. In AlianHub, Settings > Instance > Backups writes one archive with every database and, optionally, your uploaded files. This guide covers what goes in it, how restore works and how to test it without touching live data.
Key takeaways
- A backup you have never restored is a hope, not a backup.
- AlianHub writes a .tar.gz archive with a manifest and every collection of every database.
- Tick "Include uploaded files" if you store uploads on the server.
- Keep at least one copy off the host.
- Run restore drills on a separate machine or VM, never as a second Compose project on the same host.
Why self-hosters own the backup problem
Self-hosting gives you control of your data. It also gives you the job of protecting it. There is no vendor support ticket that brings back last Tuesday's tasks if a disk fails.
The good news: a project management tool has a fairly simple data shape. In AlianHub's Docker setup, the important state lives in a small number of places:
| Volume | What it holds |
|---|---|
| alianhub_mongo_data | The databases |
| alianhub_storage | Uploaded files when STORAGE_TYPE=server, the default in the image |
| alianhub_logs | Rotating logs, readable from Settings > Instance > Logs |
| alianhub_backups | Archives written by Settings > Instance > Backups |
The app creates one database per company under the MongoDB server, so a single instance may hold several workspaces. A good backup captures all of them.
What an AlianHub backup contains
Open Settings > Instance > Backups. The page writes a .tar.gz archive to BACKUP_DIR (backups/, which is a volume in Docker).
The archive contains:
- manifest.json first, describing the archive
- Every collection of every database as JSON lines in MongoDB's extended JSON, so ids and dates survive the round trip
- Uploaded files from storage/, if you tick "Include uploaded files" and use STORAGE_TYPE=server
You can download the archive from the same page or copy it off the volume.
Tip: the backups volume sits on the same host as your data. If the host dies, so do those archives. Copy at least one archive somewhere else on a schedule you trust.
If you use S3-compatible storage
With STORAGE_TYPE=wasabi, uploads live in an S3-compatible bucket rather than on disk. The "Include uploaded files" option covers storage/ when STORAGE_TYPE=server, so plan the bucket's protection separately with your storage provider.
How restore works
Restore is deliberately careful. You choose an archive, read its manifest (date, version and workspaces), and type its name to confirm.
Then a restore runs these steps in order:
- Takes a safety backup named pre-restore-*, so you can step back.
- Switches the API to maintenance. Every call except /health and the Instance console answers 503. Open tabs show a banner and recover on their own.
- Drops every collection of each database named in the archive, refills the ones the archive holds, and restores the files if they were included.
- Reruns migrations, clears caches and reconnects to the database.
Restore replaces data. It does not merge it. That is exactly why the safety backup comes first.
The version rule
Restore an archive taken by the same or an older version of AlianHub, never a newer one. If you are about to upgrade, take a backup first. If an upgrade goes wrong, you can restore that archive on the version you were running.
Run a restore drill without risking live data
The admin guide is clear on one trap, and it is worth repeating. Do not run a drill as a second Compose project on the same host. The volumes have fixed names, so the second project would attach to the live data, and restoring there would overwrite it.
A safe drill looks like this:
- Take a fresh backup on production and download it.
- Spin up AlianHub on a separate machine or VM with the same three commands you used to install.
- Restore the archive there.
- Log in, open a few projects, check recent tasks, comments and attachments.
- Note how long it took. That is your real recovery time.
Repeat it after major upgrades and whenever your setup changes. Read the full steps in the admin guide.
Alternatives if you prefer your own tools
The built-in backup is the simplest path, but you are not locked into it. The admin guide lists two alternatives:
- mongodump: run mongodump --uri "$MONGODB_URL" to back up the same data with MongoDB's own tool. With STORAGE_TYPE=server, copy storage/ as well.
- Volume snapshots: Docker users can snapshot the three volumes.
Whichever you pick, the restore drill still applies.
Keep JWT_SECRET safe too
One detail people miss: AlianHub encrypts stored secrets, like mail or storage credentials saved in Settings, with a key derived from JWT_SECRET. Keep that value stable. Rotating it makes stored secrets unreadable, and they read as unset.
Store your .env file, or at least JWT_SECRET, somewhere safe alongside your backups. A perfect database restore with the wrong secret means re-entering every stored credential.
Watch backup health from the app
Settings > Instance > Health is the first place to look when something is off. It has a Backups card that shows green when one exists and prompts you to take one when none does. The readiness card at the top lists what is still missing for a production instance.
How AlianHub's AI fits your recovery plan
Backups protect you from disks and mistakes. AlianHub's AI controls make the mistakes rarer in the first place, which matters once agents and connected AI apps start writing to your workspace.
- Agents cannot delete. Deleting a project or a task does not exist as an agent action, and a connected Claude or ChatGPT cannot delete a task, doc, comment or project.
- Undo before restore. Changes that can be undone show Undo in AI > Audit log, for 24 hours unless your admin changed it. Undoing one bad change beats restoring a whole instance.
- Pause, then investigate. An owner or admin can choose Pause all agents on a project's detail screen while checking what happened.
How to do this in AlianHub
- Before connecting AI, take a backup in Settings > Instance > Backups.
- Open AI > Audit log and filter by Agents only or Outside agents to review AI changes.
- Use Undo on any reversible change, or Export to CSV to keep a record alongside your archive.
- If something looks wrong, pause agents on the project, fix it, then resume.
A business scenario: an agency lets a connected AI reorganise tasks across a client project and one change goes wrong. Instead of a restore that would roll back everyone's work since the last archive, the admin finds the change in the audit log and undoes it. The team loses no work and the client never notices.
A simple backup routine
| How often | What to do |
|---|---|
| Before every upgrade | Take a backup in Settings > Instance > Backups |
| On a regular schedule | Take a backup and copy it off the host |
| After major changes | Run a restore drill on a separate machine |
| Always | Keep JWT_SECRET and .env somewhere safe |
If you are new to running AlianHub, start with our guide to self-hosting AlianHub with Docker, then come back here before you invite the team.
FAQ
How do I back up a self-hosted AlianHub instance?
Open Settings > Instance > Backups and create an archive. Tick "Include uploaded files" if you use server storage, then download it or copy it off the backups volume to another location.
Can I restore a backup to a newer version of AlianHub?
Restore an archive taken by the same or an older version, never a newer one. Restore reruns migrations afterwards, so an older archive is brought up to date.
Is it safe to test a restore on the same server?
Not as a second Compose project. The volumes have fixed names, so a second project would attach to the live data. Use a separate machine or VM for restore drills.
Can I use mongodump instead?
Yes. mongodump --uri "$MONGODB_URL" backs up the same data. With server storage, copy storage/ as well. Docker users can also snapshot the volumes.
Self-hosting is free, and so is peace of mind if you test your restores. Read the admin guide, try AlianHub in the live demo, and share this checklist with whoever runs your server.