Backup, restore and upkeep

Everything Collectoh knows (accounts, libraries, metadata, watch history, playlists, notes and settings) is in its database. Your media is never changed and is not part of a Collectoh backup: backing it up is up to you.

#What a backup holds

A backup is one file, such as collectoh-backup-2026-09-28-020012.tar.zst: a tar archive compressed with zstd.

The transcode cache is never included. The database alone rebuilds everything except artwork, which the server can fetch again, so a backup without artwork is small and usually the right one. Pictures you uploaded yourself live only in the metadata folder, though, so include artwork to keep them.

#Backing up

To write one now, go to Admin → Backup, tick Include artwork if you want it, and choose Back up now. Each backup is listed with its date, size, version and whether it holds artwork; Download saves a copy and Delete removes it.

For a backup every night, go to Admin → Settings → Backup:

• Nightly backup writes one each night when the maintenance window opens (02:00 on the server's clock unless you move the window).
• Backup directory is where backups are written and where Admin → Backup looks for them. Left empty, it is a backups folder in the config directory: ./config/backups with the standard compose file.
• Backups to keep (7 by default) deletes all but the newest this many after each nightly backup.
• Include artwork in the nightly backup applies to the nightly one only.

A backup on the server's own disk is lost with that disk. Point the backup directory at another disk or a network share mounted into the container, or copy the files elsewhere regularly. With Plus, the server can also keep a copy off-site for you: see Off-site backups.

#Restoring a backup

Restoring replaces everything in the database with what is in the backup.

1. In Admin → Backup, find the backup and choose Check. The server reads the whole archive, checks every entry against the manifest's checksums, and makes sure the backup is not from a newer version of Collectoh.
2. If it looks intact, choose Restore and confirm.
3. Restart the server; with Docker, run docker compose restart server.

The restore runs as one transaction, so one that fails part way leaves the database as it was. A backup from a newer server is refused, so upgrade first. Only the database is put back; the artwork and config.yaml in the archive are there for you to copy out if you need them. The DLNA server stays off after a restore until an admin switches it on again (DLNA).

To move to a new machine:

1. Install Collectoh there with the same SECRET_KEY and finish the setup wizard.
2. Copy the backup into the new server's backup directory, then check it, restore it and restart. The accounts in the backup replace the one you made in the wizard.
3. If the archive has a metadata/ folder, copy it into the new server's metadata folder.
4. Storages keep the paths they had, so mount your media at the same paths, or edit the storages under Admin → Storage.

#Off-site backups

A backup in your house is lost with the house. With Collectoh Plus, your server also sends each night's backup to your Collectoh account, on collectoh.com, so a new server can come back to everything.

• Only the database and its settings go, never your media and never artwork.
• We can't open them. Each backup is encrypted on your server before it's sent, with a key made from a passphrase only you know. The passphrase is never sent to us. Without it nobody can open these backups: not us, and not you either, so keep it somewhere safe.
• The last 30 days are kept. Older ones are deleted, and every one goes if you delete your Collectoh account.

To switch it on, go to Admin → Backup and, under Off-site backups:

1. Type a passphrase of at least 12 characters, type it again, and choose Keep this passphrase.
2. Tick Send a backup off-site every night. One goes when the maintenance window opens, whether or not nightly backups on the server's own disk are on. Send one now sends one straight away.

The server keeps a key made from the passphrase, not the passphrase itself, so the nightly backups go without anyone typing it. If you change the passphrase, the backups sent before still need the old one.

To restore one onto a new server:

1. Install Collectoh and, in the first step of the setup wizard, sign in with the same Collectoh account. Choose the old server the new one replaces.
2. Finish the wizard and open Admin → Backup. Kept for your account lists the backups from every server your account has had.
3. Choose Restore… beside one, type its passphrase and choose Check. The server fetches the backup, opens it and checks it as it would any other.
4. If it opens and is whole, choose Restore and confirm, then restart the server.

You don't need the old server's SECRET_KEY for this. Passwords and tokens for your storages, two-factor secrets, and plugin and webhook secrets come back working under the new server's own key, and the new server stays signed in to your account as itself. Artwork is fetched again. Storages keep the paths they had, so mount your media at the same paths, or edit the storages under Admin → Storage.

Restoring a backup that's already kept doesn't need Plus.

#Exporting your own data

Anyone can take their own data away as JSON from their Account page (the avatar menu, then Settings), under Export:

Rows carry titles as well as ids, so an export still makes sense years later. Course notes also export as Markdown with Export notes, on the Notes page for every course or on a course's own page.

#The maintenance window

Heavy background work runs only in a nightly window, 02:00 to 05:00 by default, so it never competes with an evening's viewing. That covers analysing audio, finding intros and credits, making scrub previews, and the maintenance tasks. Change the window under Admin → Maintenance, which also shows the time zone it follows. Outside it that work pauses, and a task still running when the window closes stops at its next checkpoint and carries on the next night. Setting the same start and end hour lets heavy work run at any time.

Each task runs once a night when the window opens, and Run now starts one straight away. Clear At night beside a task to keep it from running at night; Run now still runs it. Several only queue work (intro and credits detection, audio analysis, scrub previews), and that work still waits for the window.

Each task shows its last run: how it ended, how long it took and what it did.

On a small NAS, a scan can make playback stutter. Low-priority scanning, under Admin → Settings → Maintenance, scans one file at a time, pauses between folders and runs ffprobe at the lowest CPU priority. Scans take longer, and the setting takes effect even on a scan already running. Under Admin → Settings → Playback, End paused sessions after (minutes) ends a session left paused, so it stops holding a transcode slot.

#The trash

By default, when a file is missing from two scans in a row, its item moves to the library's trash rather than vanishing, keeping its watch history. Items an admin deletes, and those of a removed library, go there too. Admin → Trash lists each library's trash with the reason and date:

• Restore brings an item back with its watch history; Restore all does the whole library.
• Delete forever, or Empty trash, removes the records and their watch history for good.
• Empty the trash after every scan, in a library's settings, does that at the end of each completed scan.

The trash never touches files on disk. Deleting an item in the app leaves its file in place, so the next scan finds it and brings the item back. To keep something out of a library, move or delete the file itself. Collectoh deletes media files only through the API, and only when Allow media deletion is on under Admin → Settings → Library (it is off by default).

#Diagnostics

Admin → Diagnostics answers "is everything working?" on one page:

• Transcoding: the FFmpeg version, the encoder the server will use, and a short real test encode on each hardware encoder (Re-probe hardware runs them again). It also covers HEVC and HDR tone mapping, and whether the GPU's render device can be opened, with the fix when it cannot.
• Services: the database and Redis with their response times, and every job queue's counts.
• Storage and disk: whether each storage is reachable, and the free space on each volume.
• Remote access: your public address, with Test now to check that it answers.
• Search by meaning, sonic similarity, photo tags and faces: each model's state and how far it has got.

Download support bundle gives you a zip for a bug report: the diagnostics, the configuration with secrets removed, the libraries, recent scans, live sessions and the server's recent log.

#Logs

The server writes one JSON line per event to its standard output. With Docker:

docker compose logs -f server

Set LOG_LEVEL to debug for more or warn for less; the default is info. Logging in Admin → Settings → Server changes it while the server runs, the worker included, from errors only to everything; As the server was started goes back to LOG_LEVEL. Lines about a request carry its request id, the same requestId an API error returns, so a reported error can be found. Passwords, tokens and cookies are never written.

Admin → Console shows the same log in the app: the server's most recent lines, up to 5,000, newest at the bottom and following as they arrive. Choose everything, information and above, warnings and errors, or errors only, filter by any text, and Download log saves it as a file. A line keeps its message and plain values only, and anything named like a password, token or key is replaced. With a separate worker, the worker's lines are only in its own log.

Several screens keep records of their own:

• Admin → Scans: each library's last scan, with per-file errors.
• Admin → Jobs: recent failures, with Retry and Remove.
• Log on Admin → Sessions, Plugins and Webhooks: a transcode's FFmpeg output, a plugin's output and a webhook's deliveries.

#Notifications and webhooks

The bell at the top of the app gathers notifications. Admins hear when a scan finishes or fails, when someone reports a bug, and, as Plex's alerts do, when a storage can't be reached and when it's back, when a disk the server writes to is almost full (its last 5% or 5 GB, told once as it gets there), and when a maintenance task such as the nightly backup fails. Everyone hears when:

• a download is ready;
• a playlist is shared with them;
• a library is opened to them;
• an invitation they sent is accepted;
• a library they watch gains something new.

On your Account page, Notifications sets each kind In app and Push separately, chooses the libraries to watch, and turns on push in the browser you are using.

Admin → Webhooks sends the server's events to other software: a home-automation hub, a chat room, anything that accepts an HTTP POST.

1. Choose New webhook, give it a name and a URL, and pick the event families it should receive, or * for all.
2. Under Send it as, keep Collectoh's signed events for software, or choose A Discord channel or A Slack channel, or Mattermost and paste the channel's webhook URL. A chat room is told in plain sentences: new arrivals gathered into one message ("New in Films: Heat, The Matrix and 12 more"), who started watching what, a scan that failed, someone new, and a storage gone or back. Nothing else reaches the room, whatever events you picked.
3. Add any headers the receiver expects, such as an Authorization token.
4. Choose Create and copy the signing secret, which is shown only this once. The receiver uses it to check each delivery came from your server.
5. Test sends a test delivery; Log lists deliveries and their status.

A failed delivery is retried after 10 seconds, 1 minute, 10 minutes, 1 hour and 6 hours, and a webhook switches itself off after 20 deliveries in a row fail. The API reference shows what a delivery contains and how to check its signature.