Running it · Chapter 18
Backing up, restoring and updating.
Your movies, series and albums lie on your disk, not in nexcrate. What nexcrate holds itself is the database with the library, the profiles, the settings and the queue, plus the key for the stored credentials and the state of the TRaSH Guides. This chapter shows how to back that up, restore it and update nexcrate. It is meant for the operator.
Copies and the schedule
Under “Settings › System › Backups” nexcrate makes copies of its database: on a schedule, before every change to the structure of the database and when you say so. The copies lie in the folder backups in the data directory, so on the same disk as the database. If the disk dies, they go with it. A copy only becomes a real backup once you download it and keep it somewhere else.
- “Back up automatically” offers “Never”, “Daily”, “Weekly” and “Monthly”. Out of the box it is on “Weekly”. Automatic copies are made at night between 3 and 6 so that they do not run beside downloads.
- “Keep” says how many automatic copies stay, five out of the box, anything from two to 50. Older ones are removed. Copies made by hand stay until you delete them.
- “Back up now” makes a copy at once. Under “Note” you write how you will recognise it later, for example “before reworking the profiles”. With a large database this takes a few minutes on a NAS. The cached TMDB answers stay out, they come back by themselves.
The list “Copies” shows for each one when it was made, the kind (“By hand”, “Scheduled” or “Before change”), the note, the version and the size.
Downloading a backup
- Choose “Download”
Click “Download” in the row of the copy. The window “Download backup” opens.
- Set a password
Enter a “Password” and repeat it. Without this password the backup is worthless, there is no second key, and nexcrate cannot open the archive either. Write it down where you will find it in an emergency.
- Keep the file
You get an encrypted ZIP with the database, the key for the stored credentials and the TRaSH state. 7-Zip and WinRAR open it, the Windows Explorer cannot. Put it on another device.
The key matters, because everything nexcrate holds in credentials is encrypted with it: the TMDB token, the indexers, the download clients and the connections. A database without it comes back with no readable credentials. If your key is not a file secret.key in the data directory but the environment variable NEXCRATE_SECRET_KEY, it is missing from the archive, and a file KEY-MISSING.txt in the ZIP says so. Keep that value somewhere separate. The log, posters, covers and the ratings file are not in the archive. nexcrate fetches those again when needed.
Restoring a backup
Restoring replaces the whole database. There are two ways: with a copy from the list through “Restore”, or with a downloaded archive through “Restore a backup …”.
- Choose the archive
Under “Archive” choose the file, enter the password under “Password of the archive” and click “Look inside”. Until then nothing is touched.
- Read what nexcrate reports
You see when the backup was made, “From version” and the note. If it is newer than the running nexcrate, nexcrate tells you to update first. If the key is missing from the archive and this installation takes its own from
NEXCRATE_SECRET_KEY, it says that the value must be the same as when the backup was made. Otherwise the stored credentials are unreadable afterwards. - Click “Restore now”
Everything that happened in nexcrate since the backup is lost. Beforehand nexcrate makes a copy of the current state (“Before a restore”). nexcrate then restarts and is unreachable for a few minutes, because it swaps the files before anything opens the database. That needs a restart policy such as
restart: unless-stopped, which the bundled compose file sets. - Sign in again
Afterwards nobody is signed in. Sign in with the account from the backup. The page reloads by itself. If nexcrate has not answered after 45 minutes, look at the log of the container.
nexcrate only brings itself back. What happened since in the download clients, on the disk or in Radarr, Sonarr and Lidarr stays as it is. nexcrate catches up with it bit by bit afterwards. On a completely fresh installation it works at the very first start: instead of creating the account you choose “Start from a backup”.
Updating
An update is a new image. With Docker Compose you fetch it with docker compose pull and restart nexcrate with docker compose up -d. At the start nexcrate brings the database to the state of the new version itself. If the structure changes in the process, nexcrate first makes a copy of the existing database, listed as “Before change”. It counts towards “Keep”. A completely fresh installation is not copied. If you do not want to follow along unasked, put a fixed version in the compose file instead of latest and update on purpose.
“About nexcrate” says under “New version” whether a newer one is out. “Look at GitHub once a day” is on out of the box. It only asks for the newest release, and nexcrate sends nothing about itself. “Look now” asks at once. After an update nexcrate shows once what has changed. If you would rather get a message, switch on the event “New nexcrate version” under notifications, see Notifications.
If you want to go back to the older version after an update, first restore the copy “Before change” and then start the older image. The older nexcrate does not know the new structure of the database, so the copy is the safe way back.
The data directory
Everything nexcrate holds lies in /data: the database, the key, the log and the copies. The directory belongs on a local disk, never on a network share over SMB or NFS. SQLite's locking does not work reliably there, and that is how data gets lost. On a NAS use a path on an internal volume, not a mounted share.
nexcrate has a second safety net in your media: next to every title it manages lies a small file release.nex, written out of the box and adjustable under “Settings › Folders and naming › Companion files”. If the database is ever lost, nexcrate reads the library back from these files without guessing. Plex, Jellyfin and Emby ignore the file.
Good to knowA backup only counts once you have restored it. Try it on a second nexcrate before you need it, and check whether the download clients and indexers can still read their credentials. Then you know that archive, password and key fit together.