Documentation

Backup, restore and moving

Everything Home Stream knows about your library lives in one folder. Keep a copy of it and you can put the server back, or move it to another machine, without scanning or matching anything again.

What lives where

There are two kinds of thing here, and they are looked after differently.

Backing up the database

There are two safe ways. Choose whichever suits you.

While the server is running

SQLite, the database Home Stream uses, can make a consistent copy of itself while it is in use. The sqlite3 tool isn't inside the Home Stream image, so run it on the machine itself. If the machine doesn't have it, install it from your system's package manager.

Run it as the user that owns your media, the one whose numbers are HOST_UID and HOST_GID in .env. The database is readable only by that user.

cd /path/to/your/data-folder
sqlite3 openhomestream.db ".backup '/path/to/backups/homestream.db'"
chmod 600 /path/to/backups/homestream.db

Don't copy openhomestream.db with an ordinary file copy while the server is running. A plain copy is only safe once the server has stopped.

With the server stopped

From the folder that holds compose.yaml and .env (~/homestream if you used the installer):

docker compose stop
cp -a /path/to/your/data-folder /path/to/backups/homestream-data
docker compose start

This copies the whole data folder, artwork included. Anything playing will stop while the server is down, so pick a quiet moment.

The database is the part that matters most. If you can, copy the rest of the data folder as well, because account pictures and home-video collection pictures exist nowhere else.

What a backup holds, and why to keep it private

A backup is safer than you might expect, but it is still private.

• Passwords are stored only as hashes. A hash is scrambled one way, so a password can't be read back out of it.
• Sign-ins are stored as digests, never as the sign-in itself. Someone holding a copy of the database can't use it to sign in as anybody.
• It still holds your household's history: who watched what and when, favourites, playlists, names, and each account's two-factor secret.
• A copy of the whole data folder includes the recovery code. That code can reset a password from your home network until it is used.

Keep backups where only you can read them. If you keep a copy away from the machine, encrypt it first.

Restoring

1. Stop the server

   From the folder that holds compose.yaml and .env (~/homestream if you used the installer), run docker compose stop.

2. Put the file back

   Copy your backup into the data folder as openhomestream.db, replacing the one there. Make sure it belongs to the same user as before. The server tightens its permissions when it starts. If you are restoring the whole data folder, put the whole folder back in place.

3. Start it again

   Run docker compose start. Then open Settings → Server → Software Update and check that the database schema is shown with no warning beneath it.

Anything that happened after the backup was taken is gone. That includes watch progress, new accounts and settings you changed. Devices that signed in after that point will need to sign in again. Files you added to the library since then are picked up by the next scan.

An older or newer database

The database has a version of its own, called the schema. It is shown beside the server's version in Settings → Server → Software Update.

• An older backup on a newer server is brought up to date automatically when the server starts. You don't need to do anything.
• A newer database on an older server happens if you go back to an earlier release after updating. The server still starts, but it warns you, both in its log and in Software Update, that the database was written by a newer version. To fix it, update the server again, or restore the backup you took before you updated.

Moving to a new machine

1. Stop the old server

   Run docker compose stop, so nothing changes while you copy.

2. Copy the data folder across

   Copy the whole folder and keep its ownership, for example with rsync -a. On the new machine it should belong to the user that owns your media there.

3. Bring the two set-up files

   Copy compose.yaml and .env (from ~/homestream if you used the installer). Then edit DATA_DIR, MEDIA_ROOT, HOST_UID and HOST_GID to suit the new machine.

4. Start it

   Run docker compose up -d. Artwork follows the data folder wherever it goes, so pictures appear without any extra step.

5. Check your library folders

   Open Settings → Library Folders. If your library is mounted at the same path as before, everything is already there. If the path has changed, the folder shows Not connected. Choose Re-point… and pick where it is now. The server tells you how many items it found there.

The server finds your media through the folders you registered. It doesn't use a full path for every file, so re-pointing a folder is all a move needs. Watch history and favourites stay attached.

Automatic updates are set up on the machine itself, not inside Home Stream, and so is the one-time step that lets the apps find the server on their own. Running the installer on the new machine sets both up.

Moving the data folder to a bigger drive

Stop the server and copy the folder to the new drive, keeping ownership. Change DATA_DIR in .env, then run docker compose up -d.

Moving your library to a new drive

Settings → Library Folders has two different buttons for this. They are easy to mix up, so here is what each one does.

Either way, the container can only see folders it has been given. Before you start, add the new drive under volumes in compose.yaml, then run docker compose up -d:

    volumes:
      - /path/to/new-drive:/path/to/new-drive

Only the administrator can change library folders.

Updating safely

• Updates install themselves at the hour you choose in Settings → Server → Software Update. Installing one restarts the server, which stops playback.
• Each entry under Release Notes says whether the database schema changes. That is the kind of update worth taking a backup before.
• If your updates are automatic, a scheduled backup shortly before your update hour means you always have a copy from just before each update.
• If you would rather decide when to update, set HOMESTREAM_IMAGE in .env to a specific version instead of :stable.
• To go back to an earlier release, set HOMESTREAM_IMAGE to that version. If the update changed the schema, restore the backup you took before it. Then run docker compose up -d.