Backups

This page is for administrators of self-hosted instances. TaskFlow takes database dumps out of the box; what you configure is how often, how many to keep and where they go.

Backup settings live under Administration → Backups.

What is backed up

Backups cover the database — projects, issues, comments, configuration, users. Two other things are your responsibility and are not part of a dump:

• Attached files, which live in your file storage and are backed up by whatever holds them.
• deploy/.env, which holds your secrets. Keep a copy somewhere safe.

Policies

A policy is a schedule: what to dump, how often, and how much history to keep. Two policies ship with the product and can be edited or switched off:

Policy	Contents	Every	Keeps
Full	The whole database	24 hours	7 copies / 30 days
Hot	Everything except the contents of the audit log and the AI call journal	1 hour	24 copies / 2 days

The hot policy exists so that frequent dumps stay small: only the contents of those high-volume tables are left out. Table structure is always present, so any dump restores the database completely — a hot dump simply comes back without that history.

For each policy you set the interval, how many copies to keep, how many days to keep them, and whether it's switched on. You can also trigger a run by hand at any time.

Only dump when something changed

A policy can be told to skip a run when the database hasn't changed since the last dump. On a quiet instance this stops the hourly policy from filling storage with identical copies. A safety interval still forces a dump periodically even when nothing appears to have changed, so a detection failure can't leave you without recent backups.

Retention

The newest kept copies of a policy are always retained, however old they are. Beyond that count, dumps older than the retention period are deleted. When a file is removed its journal entry stays, marked as expired, so the history of runs remains readable.

Where dumps are stored

Each policy chooses a destination:

Option	Behaviour
Instance volume only (default)	The dump stays on the instance's own volume.
External storage only	The dump is taken locally, transferred out, and the local file removed.
Storage and a local copy	Transferred out, and a local copy kept.

The two latter options need a storage backend that lives outside this server, connected as an additional plugin; which storage receives dumps is selected on this same page. It's an independent choice from where issue attachments go — see File storage → Assignments.

Local dumps live on the same server

A dump on the instance volume protects you from damaging the database. It does not protect you from losing the server. For a backup worth the name, get the dumps off the machine — either by sending them to storage that lives elsewhere, or by copying the volume's contents away on a schedule of your own.

If no external storage is assigned for dumps, the two transfer options can't be selected — a run would be guaranteed to fail at delivery. If delivery does fail, the run is marked failed but the local file is kept: a network problem should never cost you a dump that was successfully taken.

The run journal

Every run is recorded with its time, the resulting file size, a checksum, and the error if it failed. Use it to confirm backups are actually happening — a policy that's been failing quietly is the classic way to discover a backup problem far too late.

Restoring

Restoring is done from the server command line with the bundled script:

bash deploy/restore-backup.sh --list             # what dumps are available
bash deploy/restore-backup.sh --latest           # restore the newest dump
bash deploy/restore-backup.sh /path/file.dump    # restore a specific file

Restoring replaces your data

A restore overwrites the contents of the database. The script asks for explicit confirmation and takes a safety dump of the current state before it starts, but treat this as a destructive operation and be sure of the dump you're restoring.

The application containers are stopped for the duration of the restore, and the script adapts to how your database is deployed — whether it's the bundled PostgreSQL or an external one. Make sure the host has free disk space roughly the size of the dump.

Instances on a shared database

If your instance uses a shared or managed PostgreSQL that its owner already backs up centrally, you can stop TaskFlow from taking its own dumps by setting BACKUP_ENABLED=0. The interface then shows a banner saying backups are switched off — deliberately distinguishable from the backup service being unavailable.

Backups work the same either way: dumps cover this instance's database and never touch neighbouring databases in the same cluster.

Where to go next

• File storage — configuring the destination for dumps.
• Installation → Upgrades — always back up before upgrading.
• Configuration — the backup-related environment variables.