Skip to content

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 ​

SettingThis homelab
Host address10.120.40.105
Domainmedia-kopia.home.rwk.me
Dashboardhttps://media-kopia.home.rwk.me
Direct HTTPShttps://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/kopia

Create 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-stopped

The 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-server

Skip 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.key

Use 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=/repository

For 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 ps

Use 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
fi

The 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.sh

Replace <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.target

Choose 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.service

Verify 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> /restore

Use 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 today

Keep 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.