Appearance
Media Server Backups
Kopia protects Jellyfin and Servarr application state in an encrypted, versioned repository. Media files are excluded and require their own NAS backup policy. A snapshot's success is not proof that its databases can be restored.
Prepare the media host and application stacks first. Exact production runner commands, credentials, and AI recovery procedures are in Kopia · Internal Operations.
Access and storage
| Setting | This homelab |
|---|---|
| Host address | 10.120.40.105 |
| Domain | media-kopia.home.rwk.me |
| Dashboard | https://media-kopia.home.rwk.me |
| Direct HTTPS | https://10.120.40.105:51515 |
| Project | /docker/kopia |
| Repository | /mnt/unaspro/server-backups/media-server/repository |
| Sources | /docker/jellyfin and /docker/servarr, mounted read-only under /source |
For another homelab, choose your own paths, domain, and accounts. NAS storage is optional; use a supported repository destination and retain a recovery copy outside the application host. Never initialize a new repository over an existing recovery repository.
Configure Kopia
Run as your deployment account:
sh
sudo install -d -o "$(id -u)" -g "$(id -g)" -m 0750 /docker/kopia
cd /docker/kopiaCreate compose.yaml:
yaml
services:
kopia:
image: kopia/kopia:0.23.1
container_name: kopia
hostname: media-server
user: "${PUID}:${PGID}"
environment:
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_CONFIG_PATH: /app/config/repository.config
KOPIA_LOG_DIR: /app/logs
KOPIA_PASSWORD: ${KOPIA_REPOSITORY_PASSWORD}
KOPIA_SERVER_PASSWORD: ${KOPIA_SERVER_PASSWORD}
KOPIA_SERVER_USERNAME: ${KOPIA_SERVER_USERNAME}
TZ: ${TZ}
USER: backup-user
command:
- server
- start
- --address=0.0.0.0:51515
- --tls-cert-file=/app/config/kopia.crt
- --tls-key-file=/app/config/kopia.key
- --ui-title-prefix=Media Server
volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs
- ./restore:/restore
- /mnt/unaspro/server-backups/media-server/repository:/repository
- /docker/jellyfin:/source/jellyfin:ro
- /docker/servarr:/source/servarr:ro
ports:
- "${SERVER_IP}:51515:51515"
healthcheck:
test: ["CMD", "kopia", "repository", "status"]
interval: 30s
timeout: 10s
retries: 5
start_period: 30s
security_opt:
- no-new-privileges:true
restart: unless-stoppedThe backup-user value is an example Kopia source identity, not a host account requirement. On an existing lab deployment, preserve the existing identity and environment values documented privately. Choose a source identity once and keep policy, snapshot commands, and UI history consistent with it.
Create .env alongside Compose:
dotenv
SERVER_IP=10.120.40.105
PUID=1000
PGID=1000
TZ=America/Chicago
KOPIA_SERVER_USERNAME=backup-user
KOPIA_SERVER_PASSWORD=<independent-ui-password>
KOPIA_REPOSITORY_PASSWORD=<independent-repository-password>
JELLYFIN_API_KEY=<jellyfin-backup-api-key>Set UID/GID to the deployment account's actual IDs. Generate independent strong UI and repository passwords and save them securely. The repository password protects the encryption keys and cannot be reset to recover data if it is lost. Keep .env private with chmod 600 .env; retain original credentials during a rebuild.
Create an API key named kopia-backup in Jellyfin's Dashboard → API Keys and set JELLYFIN_API_KEY to that token. The runner expects the unquoted 32-character hexadecimal token in this field; it sends it privately through Jellyfin's Authorization header. Preserve existing application credentials during updates.
The container runs unprivileged with read-only application source mounts and no Docker socket. The host coordinates consistent application snapshots. Changing the container's source identity does not migrate existing policies or history automatically.
Verify the destination and create TLS credentials
On this NAS-backed host, verify the real backup mount before creating directories:
sh
findmnt /mnt/unaspro/server-backups
test -w /mnt/unaspro/server-backups/media-serverSkip the mount check only when deliberately using a different storage destination, and adjust the repository binding accordingly. A directory existing on the system disk is not proof that the NAS is mounted.
From /docker/kopia, create the writable container directories and self-signed upstream certificate:
sh
mkdir -p config cache logs restore /mnt/unaspro/server-backups/media-server/repository
chmod 700 config cache logs restore /mnt/unaspro/server-backups/media-server/repository
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -days 3650 \
-keyout config/kopia.key -out config/kopia.crt \
-subj '/CN=media-server' \
-addext 'subjectAltName=DNS:media-server,IP:10.120.40.105'
chmod 600 config/kopia.keyUse your server name/address in the certificate on another host. Protect and renew the certificate as needed; the proxy's client-facing certificate is managed separately.
Initialize the encrypted repository
For a new, empty repository:
sh
docker compose config --quiet
docker compose pull
docker compose run --rm --entrypoint kopia kopia repository create filesystem --path=/repositoryFor recovery from an existing repository, connect with its original password using repository connect filesystem --path=/repository instead. Do not run repository creation as a repair action. See Kopia's repository and restore guide.
Configure the example source policy before the first snapshot:
sh
docker compose run --rm --entrypoint kopia kopia policy set \
backup-user@media-server:/source \
--manual --compression=zstd \
--keep-latest=10 --keep-hourly=0 --keep-daily=7 \
--keep-weekly=4 --keep-monthly=12 --keep-annual=3 \
--add-ignore=jellyfin/config/cache \
--add-ignore=jellyfin/config/log \
--add-ignore=jellyfin/config/data/transcodes
docker compose up -d
docker compose psUse the source identity matching your deployment. These retention tiers overlap; they are not a guarantee of a fixed total snapshot count. --manual leaves scheduling to the host so application consistency can be coordinated first. Review retention policies before adapting them.
Configure private HTTPS access
Resolve media-kopia.home.rwk.me to Nginx Proxy Manager at 10.120.40.101. Forward using HTTPS to 10.120.40.105:51515, enable WebSockets, select the certificate covering the hostname, and force HTTPS. Handle the self-signed upstream certificate deliberately and keep Kopia authentication enabled.
Use DNS-only records in Cloudflare, as explained in the NPM guide. Clients require an allowed local-network or Tailscale route. This setup does not require WAN port forwarding for the service names.
Verify dashboard login and repository visibility. Protect direct backend access separately from any proxy access list.
Make application-consistent snapshots
This lab's coordinated runner
The production backup.sh asset remains in servers/media-server/kopia in the homelab repository. It creates and validates a native Jellyfin database archive while playback stays online, takes a logical Streamystats dump, briefly stops the running Servarr applications except Gluetun and qBittorrent, then snapshots /source and restores the selected services. Seerr's surrounding files are captured live, so do not assume every application has an equivalent stopped-database consistency guarantee.
The runner verifies the Jellyfin archive is present and can be restored from the snapshot before removing local jellyfin-backup-*.zip archives. Scheduled backups and deployments share a host lock. Production installation and exact source identities are in the internal guide.
Install the consistent backup runner
Create /docker/kopia/backup.sh using the example below. It is the repository runner with its Kopia source identity changed to the public example backup-user. Preserve the actual existing source identity on a running deployment. The host needs Bash, curl, jq, Docker Compose, and flock; the pinned Jellyfin release must support its native backup API.
Consistent backup runner example
bash
#!/usr/bin/env bash
set -Eeuo pipefail
readonly MEDIA_MOUNT=/mnt/unaspro/media
readonly BACKUP_MOUNT=/mnt/unaspro/server-backups
readonly SERVARR_COMPOSE=/docker/servarr/compose.yaml
readonly JELLYFIN_COMPOSE=/docker/jellyfin/compose.yaml
readonly KOPIA_ENV=/docker/kopia/.env
readonly JELLYFIN_BACKUP_DIR=/docker/jellyfin/config/data/data/backups
readonly JELLYFIN_CONTAINER_BACKUP_DIR=/config/data/data/backups
declare -a servarr_services=()
declare -a requested_services=()
declare -a stopped_container_ids=()
scoped=false
backup_jellyfin=true
if (($#)); then
[[ "$1" == --services && $# -gt 1 ]]
shift
scoped=true
backup_jellyfin=false
requested_services=("$@")
for service in "${requested_services[@]}"; do
case "$service" in
jellyfin) backup_jellyfin=true ;;
kopia) ;; # Its configuration is snapshotted separately while it runs.
gluetun) ;; # Keep the namespace available while selected consumers restart.
*) servarr_services+=("$service") ;;
esac
done
fi
create_database_dump() {
local container="$1"
local destination="$2"
shift 2
mkdir -p -- "$(dirname -- "$destination")"
docker exec "$container" "$@" > "$destination.tmp"
chmod 0600 "$destination.tmp"
mv -- "$destination.tmp" "$destination"
}
jellyfin_api() {
local method="$1"
local path="$2"
shift 2
curl \
--config <(
printf 'header = "Authorization: MediaBrowser Token=\\\"%s\\\""\n' \
"$JELLYFIN_API_KEY"
) \
--fail-with-body \
--silent \
--show-error \
--request "$method" \
--url "http://$SERVER_IP:8096$path" \
"$@"
}
create_jellyfin_backup() {
local manifest
local container_path
local archive_name
manifest="$({
jellyfin_api POST /Backup/Create \
--header 'Content-Type: application/json' \
--data '{"Database":true,"Metadata":false,"Trickplay":false,"Subtitles":false}'
})"
container_path="$(
jq -er '.Path // .path' <<< "$manifest"
)"
case "$container_path" in
"$JELLYFIN_CONTAINER_BACKUP_DIR"/jellyfin-backup-*.zip)
;;
*)
printf 'Jellyfin returned an unexpected backup path: %s\n' \
"$container_path" >&2
return 1
;;
esac
archive_name="${container_path##*/}"
jellyfin_backup_path="$JELLYFIN_BACKUP_DIR/$archive_name"
test -s "$jellyfin_backup_path"
jellyfin_api GET /Backup/Manifest \
--get \
--data-urlencode "path=$container_path" | \
jq -e \
--arg path "$container_path" \
'(.Path // .path) == $path and
((.Options // .options).Database //
(.Options // .options).database) == true' \
>/dev/null
printf 'Created and validated Jellyfin database backup: %s\n' \
"$archive_name"
}
verify_jellyfin_backup_in_snapshot() {
local archive_name="${jellyfin_backup_path##*/}"
local snapshot_json
local root_object_id
local snapshot_id
local verify_dir
local container_verify_dir
local verify_code=0
snapshot_json="$(
docker exec kopia kopia snapshot list \
backup-user@media-server:/source --json | \
jq -ec 'max_by(.endTime)'
)"
root_object_id="$(jq -er '.rootEntry.obj' <<< "$snapshot_json")"
snapshot_id="$(jq -er '.id' <<< "$snapshot_json")"
docker exec kopia kopia list \
"$root_object_id/jellyfin/config/data/data/backups" | \
grep -Fxq -- "$archive_name"
verify_dir="$(
mktemp -d /docker/kopia/restore/jellyfin-backup-verify.XXXXXX
)"
container_verify_dir="/restore/${verify_dir#/docker/kopia/restore/}"
docker exec kopia kopia snapshot restore \
--write-files-atomically \
"$root_object_id/jellyfin/config/data/data/backups/$archive_name" \
"$container_verify_dir/restored-archive" || verify_code=$?
if ((verify_code == 0)); then
cmp --silent \
"$jellyfin_backup_path" \
"$verify_dir/restored-archive" || verify_code=$?
fi
find "$verify_dir" -mindepth 1 -delete
rmdir "$verify_dir"
((verify_code == 0)) || return "$verify_code"
printf 'Restored and verified Jellyfin backup from Kopia snapshot %s.\n' \
"$snapshot_id"
}
remove_local_jellyfin_backups() {
local archive
while IFS= read -r -d '' archive; do
rm -f -- "$archive"
done < <(
find "$JELLYFIN_BACKUP_DIR" \
-maxdepth 1 \
-type f \
-name 'jellyfin-backup-*.zip' \
-print0
)
printf 'Removed local Jellyfin backup archives after the Kopia snapshot.\n'
}
restore_services() {
local exit_code=$?
local restart_code=0
trap - EXIT INT TERM
if [[ "$scoped" == true ]] && ((${#stopped_container_ids[@]})); then
# Restart the exact stopped containers without evaluating Compose dependencies.
docker start "${stopped_container_ids[@]}" >/dev/null || restart_code=$?
elif [[ "$scoped" == false ]] && ((${#servarr_services[@]})); then
docker compose -f "$SERVARR_COMPOSE" up -d --no-deps \
"${servarr_services[@]}" || \
restart_code=$?
fi
if ((exit_code)); then
exit "$exit_code"
fi
exit "$restart_code"
}
findmnt -rn --mountpoint "$MEDIA_MOUNT" >/dev/null
findmnt -rn --mountpoint "$BACKUP_MOUNT" >/dev/null
test -d "$BACKUP_MOUNT/media-server/repository"
test "$(docker inspect --format '{{.State.Running}}' kopia)" = true
: "${SERVER_IP:?SERVER_IP must be defined}"
if [[ "$backup_jellyfin" == true ]]; then
test -r "$KOPIA_ENV"
JELLYFIN_API_KEY="$(
awk -F= '$1 == "JELLYFIN_API_KEY" {
print substr($0, index($0, "=") + 1)
exit
}' "$KOPIA_ENV"
)"
: "${JELLYFIN_API_KEY:?JELLYFIN_API_KEY must be defined in $KOPIA_ENV}"
[[ "$JELLYFIN_API_KEY" =~ ^[[:xdigit:]]{32}$ ]]
command -v curl >/dev/null
command -v jq >/dev/null
install -d -m 0755 "$JELLYFIN_BACKUP_DIR"
jellyfin_backup_path=
create_jellyfin_backup
fi
if [[ "$scoped" == false ]]; then
mapfile -t servarr_services < <(
docker compose -f "$SERVARR_COMPOSE" ps --services --filter status=running | \
awk '$0 != "gluetun" && $0 != "qbittorrent"'
)
else
# Reject unknown names before stopping anything, including accidental options.
known_services="$(docker compose -f "$SERVARR_COMPOSE" config --services)
$(docker compose -f "$JELLYFIN_COMPOSE" config --services)
kopia"
for service in "${requested_services[@]}"; do
grep -Fxq -- "$service" <<< "$known_services"
done
fi
trap restore_services EXIT INT TERM
if printf '%s\n' "${servarr_services[@]}" | grep -Fxq streamystats; then
create_database_dump \
streamystats \
/docker/servarr/streamystats/backup-data/streamystats.dump \
pg_dump --clean --if-exists --no-owner --format=custom \
--username=postgres streamystats
fi
if ((${#servarr_services[@]})); then
if [[ "$scoped" == true ]]; then
for service in "${servarr_services[@]}"; do
if [[ "$(docker inspect --format '{{.State.Running}}' "$service")" == true ]]; then
stopped_container_ids+=("$(docker inspect --format '{{.Id}}' "$service")")
fi
done
if ((${#stopped_container_ids[@]})); then
docker stop --time 60 "${stopped_container_ids[@]}" >/dev/null
fi
else
docker compose -f "$SERVARR_COMPOSE" stop "${servarr_services[@]}"
fi
fi
docker exec kopia kopia snapshot create /source \
--override-source=backup-user@media-server:/source
if [[ "$backup_jellyfin" == true ]]; then
verify_jellyfin_backup_in_snapshot
remove_local_jellyfin_backups
fi
if [[ "$scoped" == true ]] && printf '%s\n' "${requested_services[@]}" | grep -Fxq kopia; then
docker exec kopia kopia snapshot create /app/config \
--override-source=backup-user@media-server:/docker/kopia/config
fiThe paths match this lab. For another host, update the mount preflight checks, Compose paths, source identity, and Jellyfin backup paths consistently with your installation. This runner expects the shared applications and their current container names; adapt deliberately if you omit components. Do not remove storage checks merely to bypass a missing repository.
Set chmod 700 /docker/kopia/backup.sh. Review a manual backup and restore test before enabling unattended scheduling. The host runner can stop and start containers through Docker; it should be owned and controlled by the deployment account.
Schedule backups
Create /etc/systemd/system/kopia-media-backup.service:
ini
[Unit]
Description=Back up media-server application data with Kopia
Requires=docker.service mnt-unaspro-media.mount mnt-unaspro-server\x2dbackups.mount
After=docker.service mnt-unaspro-media.mount mnt-unaspro-server\x2dbackups.mount
[Service]
Type=oneshot
User=<deployment-user>
SupplementaryGroups=docker
EnvironmentFile=/etc/environment
ExecStart=/usr/bin/flock --exclusive --wait 1800 /docker/.media-server-maintenance.lock /docker/kopia/backup.shReplace <deployment-user> with the account owning the deployment and having Docker access. The NAS mount-unit names apply to the paths in this lab; adapt the requirements to your actual storage. Keep EnvironmentFile=/etc/environment where it supplies SERVER_IP, or supply the required host address in a protected service environment. Ensure the account can open /docker/.media-server-maintenance.lock. Docker access is root-equivalent.
Create /etc/systemd/system/kopia-media-backup.timer:
ini
[Unit]
Description=Run the media-server Kopia backup daily
[Timer]
OnCalendar=*-*-* 04:00:00 America/Chicago
Persistent=true
RandomizedDelaySec=10m
Unit=kopia-media-backup.service
[Install]
WantedBy=timers.targetChoose your timezone and schedule. Persistent timers catch missed runs after boot, and the random delay adds up to ten minutes. Reload, enable, and inspect the timer:
sh
sudo systemctl daemon-reload
sudo systemctl enable --now kopia-media-backup.timer
systemctl list-timers kopia-media-backup.timer
sudo systemctl start kopia-media-backup.service
systemctl status kopia-media-backup.serviceVerify a new snapshot and restored application state. Every automated deployment or backup touching these applications must use the same coordination lock. Leave Kopia's independent automatic snapshot scheduling disabled for this source so it does not bypass the runner's consistency steps.
Restore and validate
List snapshots, inspect the root object ID, and restore into a new staging directory:
sh
docker exec kopia kopia snapshot list backup-user@media-server:/source
docker exec kopia kopia list <root-object-id>
docker exec kopia kopia snapshot restore <root-object-id> /restoreUse your deployment's original source identity. The container's /restore maps to /docker/kopia/restore on the host. Use a new empty staging subdirectory for separate recovery attempts and never overwrite live databases while applications are running.
Validate the restored configuration and databases in an isolated test deployment before replacement. Streamystats requires its logical dump to be restored into a compatible PostgreSQL instance, and the production Jellyfin workflow uses its native archive for the consistent database recovery. Restore each app's matching credentials, keys, ownership, and image version. Confirm login, library state, requests, analytics history, and representative playback.
The production Jellyfin restore-test helper runs in a network-isolated temporary container and requires at least 25 GiB free local space; its exact monthly schedule and commands are internal. Kopia repository verification can check stored data integrity, but does not replace starting the application with restored state.
Maintenance checks
sh
cd /docker/kopia
docker compose ps
docker exec kopia kopia repository status
docker exec kopia kopia maintenance info
systemctl list-timers kopia-media-backup.timer
journalctl -u kopia-media-backup.service --since todayKeep logs and snapshots private. Preserve the repository password, original identity, configuration, and recovery procedures outside the host. Never delete the repository as part of a container rebuild or change encryption credentials without a tested recovery plan.