Backups

Back up your server

What tofa backs up on its own, what you should copy yourself, and how a restore works when you need one.

4 min read

tofa automatically backs up its database, including matches, watch history, settings, users, and edit locks. Back up your media files separately.

What backs up automatically#

On a standard install (the built-in database), your server takes a database backup every day, keeps the most recent seven, and verifies each one by test-restoring it into a scratch database and checking the result. Verified backups get a "verified" chip in the admin UI, so you are never trusting an untested file.

Everything lives under Admin, then Settings, then Database: the backup list, a Backup Now button, the schedule (6 hours to weekly), and how many to keep.

Put backups on a second disk

By default backups land inside the data directory, on the same disk as the database they protect. A dead disk then takes both. The Database page lets you move the backup folder elsewhere, and moving brings the existing backups along.

If a backup can't fit on the disk, the server refuses to write a truncated one and the page tells you, rather than quietly keeping a backup that wouldn't restore.

What to copy yourself#

A database backup covers the database. To back up the rest of your server, also copy these from the data directory:

config.toml and the identity/ folder, the server's local settings and keys.
metadata/images/ if you care about re-download time: artwork comes back on its own after a restore, but for a big library that takes a while.

The cache/ folder never needs backing up. It regenerates, though preview thumbnails can take days for a large library, so don't delete it casually either.

Where the data directory lives: on Docker it is the tofa-data volume from your compose file; on Linux ~/.tofa; on macOS ~/Library/Application Support/tofa; on Windows %PROGRAMDATA%\tofa.

Restoring#

On the Database page, pick a backup and confirm by typing RESTORE. The server sets the old database aside, restores the backup, and restarts itself; on Windows it asks you to restart it. Afterwards a banner names exactly which backup you are now running on.

Two safety nets behind that:

The replaced database is kept next to the new one for two weeks, so even a restore can be undone.
If the database is ever damaged, by a power cut or a full disk at the wrong moment, the server notices at startup and restores the newest verified backup on its own, keeping the damaged copy aside for inspection.

A restore needs roughly double the database's size in free space while it runs, since the old copy is preserved beside the new one.

After a total loss#

Machine died, disk gone: install tofa fresh, sign in, and restore your latest database backup. Your matches, users, settings, and edit locks come back from the backup. Watch history, watchlists, and preferences also live with your account in the cloud, so they flow back even to a server restored from an older backup. Artwork re-downloads and previews regenerate over the following days.

This is also why the backup folder belongs on a different disk, or synced somewhere else entirely, it is the one file that turns a rebuild from a weekend into minutes.

If you run your own PostgreSQL#

External-database installs manage their own backups; the Database page says so and the built-in scheduler, verification, and auto-restore don't apply. Use your normal pg_dump routine, and still copy config.toml and identity/ from the data directory.

Good to know#

Manual backups count against retention. Pressing Backup Now repeatedly prunes older automatic backups once you pass the keep limit.
Schedule changes apply after the next restart; the page says so when you save.
In-place updates back up first automatically. Docker updates don't, so take one before a big version jump. See Keep your server up to date.
On Docker, if you point backups at a host folder, make sure the container's user can write to it.

Still stuck? Getting help & feedback covers what to send us.