Hands-on 06-bazarr-and-subtitle-automation: Lab

title

Stage and validate a Bazarr Compose definition

objective

Create a local deployment manifest, safe fixture directories, and a validation report while keeping every lab mutation inside the class directory.

steps

step

1

instruction

Create the isolated class directory structure.

command

install -d /opt/lab-classroom/class61/config /opt/lab-classroom/class61/media/movies /opt/lab-classroom/class61/media/tv /opt/lab-classroom/class61/artifacts

step

2

instruction

Record the current numeric user and group identifiers for the staged container configuration.

command

printf 'PUID=%s\nPGID=%s\nTZ=Etc/UTC\n' "$(id -u)" "$(id -g)" > /opt/lab-classroom/class61/.env

step

3

instruction

Create the Compose definition. It binds the web interface to loopback, avoids privileged mode and host networking, and maps only class fixture directories.

command

cat > /opt/lab-classroom/class61/compose.yml <<'EOF'
services:
bazarr:
image: lscr.io/linuxserver/bazarr:latest
container_name: class61-bazarr
environment:
PUID: ${PUID}
PGID: ${PGID}
TZ: ${TZ}
ports:
- "127.0.0.1:6767:6767"
volumes:
- /opt/lab-classroom/class61/config:/config
- /opt/lab-classroom/class61/media/movies:/movies
- /opt/lab-classroom/class61/media/tv:/tv
restart: unless-stopped
EOF

step

4

instruction

Create an explicit inventory fixture. These are descriptive records, not playable media files.

command

cat > /opt/lab-classroom/class61/artifacts/media-inventory.json <<'EOF'
{
"movies": [
{
"title": "Training Movie",
"manager_path": "/movies/Training Movie/Training Movie.mkv",
"desired_languages": ["en"],
"existing_sidecars": []
}
],
"episodes": [
{
"series": "Training Series",
"episode": "S01E01",
"manager_path": "/tv/Training Series/Season 01/Training Series - S01E01.mkv",
"desired_languages": ["en"],
"existing_sidecars": ["Training Series - S01E01.en.srt"]
}
]
}
EOF

step

5

instruction

Create a validator that checks the staged manifest for required path, port, identity, and privilege controls.

command

cat > /opt/lab-classroom/class61/validate.py <<'PY'
from pathlib import Path
import json

root = Path('/opt/lab-classroom/class61')
compose_path = root / 'compose.yml'
env_path = root / '.env'
inventory_path = root / 'artifacts' / 'media-inventory.json'

compose = compose_path.read_text(encoding='utf-8')
env_lines = env_path.read_text(encoding='utf-8').splitlines()
env = dict(line.split('=', 1) for line in env_lines if '=' in line)
inventory = json.loads(inventory_path.read_text(encoding='utf-8'))

checks = {
'loopback_port_binding': '127.0.0.1:6767:6767' in compose,
'config_path_scoped': '/opt/lab-classroom/class61/config:/config' in compose,
'movie_path_scoped': '/opt/lab-classroom/class61/media/movies:/movies' in compose,
'tv_path_scoped': '/opt/lab-classroom/class61/media/tv:/tv' in compose,
'puid_present': env.get('PUID', '').isdigit(),
'pgid_present': env.get('PGID', '').isdigit(),
'timezone_present': bool(env.get('TZ')),
'not_privileged': 'privileged: true' not in compose.lower(),
'no_host_network': 'network_mode: host' not in compose.lower(),
'inventory_has_movie': len(inventory.get('movies', [])) == 1,
'inventory_has_episode': len(inventory.get('episodes', [])) == 1
}

report = {
'status': 'PASS' if all(checks.values()) else 'FAIL',
'checks': checks,
'containers_started': False,
'external_services_contacted': False
}
output = root / 'artifacts' / 'validation-report.json'
output.write_text(json.dumps(report, indent=2) + '\n', encoding='utf-8')
print(json.dumps(report, indent=2))
raise SystemExit(0 if report['status'] == 'PASS' else 1)
PY
python3 /opt/lab-classroom/class61/validate.py

step

6

instruction

If Docker Compose is installed, render and validate the Compose model without starting a service. If it is not installed, retain the Python validation result.

command

if command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; then docker compose --env-file /opt/lab-classroom/class61/.env -f /opt/lab-classroom/class61/compose.yml config --quiet; else printf '%s\n' 'Docker Compose unavailable; Python validation remains authoritative for this isolated lab.'; fi

step

7

instruction

Save known-good copies that can be used to reverse later edits during the exercise.

command

cp /opt/lab-classroom/class61/compose.yml /opt/lab-classroom/class61/artifacts/compose.known-good.yml && cp /opt/lab-classroom/class61/.env /opt/lab-classroom/class61/artifacts/env.known-good

step

8

instruction

Review the generated validation report and confirm that no container was started.

command

cat /opt/lab-classroom/class61/artifacts/validation-report.json

production_follow_up

Pin the container image to a version or immutable digest tested in the local environment rather than accepting unreviewed changes indefinitely.
Back up the Bazarr configuration before upgrades or broad profile changes.
Confirm that Bazarr, Sonarr, and Radarr use consistent container paths or document each required path mapping.
Use dedicated Sonarr and Radarr API keys and protect them as secrets.
Test one language profile and a small title set before enabling scheduled searches for a full library.
Verify media ownership and group permissions before granting Bazarr write access.
Place remote access behind authenticated HTTPS rather than exposing the application port directly.