scope_rule

Every file created or changed by this lab must remain below /opt/lab-classroom/class54/. Do not substitute a system application directory, a normal user home directory, or another service's data directory.

steps

step

1

title

Prepare isolated directories

commands

cd /opt/lab-classroom/class54
mkdir -p app data home tmp cache config state logs mock

notes

The class directory must already exist. The subdirectories provide explicit locations for application, persistent, temporary, and teaching-service files.

step

2

title

Download the current official Prowlarr release for the host architecture

commands

cd /opt/lab-classroom/class54
cat > download_prowlarr.py <<'PY'
import hashlib
import json
import platform
import urllib.request
from pathlib import Path

root = Path('/opt/lab-classroom/class54')
api = 'https://api.github.com/repos/Prowlarr/Prowlarr/releases/latest'
machine = platform.machine().lower()
architectures = {
'x86_64': 'x64',
'amd64': 'x64',
'aarch64': 'arm64',
'arm64': 'arm64'
}
if machine not in architectures:
raise SystemExit(f'Unsupported lab architecture: {machine}')
arch = architectures[machine]
request = urllib.request.Request(api, headers={'User-Agent': 'OtaconsKeep-Homelab-Academy-Class54'})
with urllib.request.urlopen(request, timeout=30) as response:
release_bytes = response.read()
release = json.loads(release_bytes)
(root / 'release.json').write_bytes(release_bytes)
assets = [
asset for asset in release.get('assets', [])
if asset.get('name', '').lower().endswith(f'linux-core-{arch}.tar.gz')
and 'musl' not in asset.get('name', '').lower()
]
if len(assets) != 1:
names = [asset.get('name', '') for asset in release.get('assets', [])]
raise SystemExit(f'Expected one Linux {arch} archive; candidates were: {names}')
asset = assets[0]
archive = root / 'prowlarr.tar.gz'
asset_request = urllib.request.Request(asset['browser_download_url'], headers={'User-Agent': 'OtaconsKeep-Homelab-Academy-Class54'})
with urllib.request.urlopen(asset_request, timeout=120) as response, archive.open('wb') as output:
while True:
block = response.read(1024 * 1024)
if not block:
break
output.write(block)
digest = hashlib.sha256(archive.read_bytes()).hexdigest()
(root / 'prowlarr.sha256').write_text(f'{digest} prowlarr.tar.gz\n', encoding='utf-8')
(root / 'selected-release.txt').write_text(
f"tag={release.get('tag_name', '')}\nasset={asset['name']}\nurl={asset['browser_download_url']}\n",
encoding='utf-8'
)
print((root / 'selected-release.txt').read_text(), end='')
print((root / 'prowlarr.sha256').read_text(), end='')
PY
python3 /opt/lab-classroom/class54/download_prowlarr.py

notes

Python validates HTTPS certificates through its standard TLS configuration. The generated digest is a local audit record, not an independent publisher signature.

step

3

title

Validate archive paths and extract Prowlarr

commands

cd /opt/lab-classroom/class54
cat > extract_prowlarr.py <<'PY'
import shutil
import tarfile
from pathlib import Path, PurePosixPath

root = Path('/opt/lab-classroom/class54')
archive = root / 'prowlarr.tar.gz'
destination = root / 'app'
if any(destination.iterdir()):
raise SystemExit('The app directory is not empty; preserve or clear it before extraction.')
with tarfile.open(archive, 'r:gz') as bundle:
members = bundle.getmembers()
for member in members:
path = PurePosixPath(member.name)
if path.is_absolute() or '..' in path.parts:
raise SystemExit(f'Unsafe archive path: {member.name}')
if member.issym() or member.islnk() or member.isdev() or member.isfifo():
raise SystemExit(f'Unsupported special archive entry: {member.name}')
bundle.extractall(destination, members=members)
with (root / 'archive-files.txt').open('w', encoding='utf-8') as listing:
for member in members:
listing.write(member.name + '\n')
binaries = list(destination.rglob('Prowlarr'))
if len(binaries) != 1 or not binaries[0].is_file():
raise SystemExit(f'Expected exactly one Prowlarr executable; found: {binaries}')
binaries[0].chmod(binaries[0].stat().st_mode | 0o100)
(root / 'prowlarr-binary.txt').write_text(str(binaries[0]) + '\n', encoding='utf-8')
print(binaries[0])
PY
python3 /opt/lab-classroom/class54/extract_prowlarr.py

notes

The extractor rejects absolute paths, parent traversal, links, devices, and named pipes before extraction.

step

4

title

Create an isolated Prowlarr launcher

commands

cd /opt/lab-classroom/class54
cat > start-prowlarr.sh <<'SH'

!/bin/sh

set -eu
ROOT=/opt/lab-classroom/class54
export HOME="$ROOT/home"
export TMPDIR="$ROOT/tmp"
export XDG_CACHE_HOME="$ROOT/cache"
export XDG_CONFIG_HOME="$ROOT/config"
export XDG_STATE_HOME="$ROOT/state"
export DOTNET_CLI_HOME="$ROOT/home"
BIN=$(cat "$ROOT/prowlarr-binary.txt")
if [ ! -x "$BIN" ]; then
echo "Prowlarr executable is missing or not executable: $BIN" >&2
exit 1
fi
exec "$BIN" -nobrowser -data="$ROOT/data"
SH
chmod u+x /opt/lab-classroom/class54/start-prowlarr.sh
cd /opt/lab-classroom/class54 && nohup ./start-prowlarr.sh > ./logs/prowlarr-console.log 2>&1 & echo $! > ./prowlarr.pid
sleep 8
python3 -c "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:9696', timeout=10).status)"

notes

If the final command does not print a successful HTTP status, inspect logs/prowlarr-console.log before continuing.

step

5

title

Create and start the local Torznab teaching indexer

commands

cd /opt/lab-classroom/class54
cat > mock/mock_indexer.py <<'PY'
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, urlparse
from datetime import datetime, timezone
from pathlib import Path

ROOT = Path('/opt/lab-classroom/class54')
LOG = ROOT / 'logs' / 'mock-indexer.log'
CAPS = b'''<?xml version="1.0" encoding="UTF-8"?>

def do_GET(self):
    parsed = urlparse(self.path)
    params = parse_qs(parsed.query)
    if parsed.path in ('/', '/api') and params.get('t', [''])[0] == 'caps':
        body = CAPS
        status = 200
        content_type = 'application/xml; charset=utf-8'
    elif parsed.path in ('/', '/api') and params.get('t', [''])[0] in ('search', 'tvsearch', 'movie'):
        body = search_xml(params.get('q', ['Class 54 Test'])[0])
        status = 200
        content_type = 'application/xml; charset=utf-8'
    elif parsed.path == '/':
        body = b'Class 54 Torznab teaching indexer\n'
        status = 200
        content_type = 'text/plain; charset=utf-8'
    else:
        body = b'No payload is provided by this teaching endpoint.\n'
        status = 404
        content_type = 'text/plain; charset=utf-8'
    self.send_response(status)
    self.send_header('Content-Type', content_type)
    self.send_header('Content-Length', str(len(body)))
    self.end_headers()
    self.wfile.write(body)

notes

The teaching indexer binds only to loopback and returns synthetic XML. Its download URL deliberately returns no payload.

step

6

title

Complete Prowlarr first-run configuration

commands

notes

Open http://127.0.0.1:9696 in a browser. Complete any first-run authentication prompt. Use a unique lab credential and do not reuse a production password. Interface wording can vary by release.

step

7

title

Add the Generic Torznab teaching indexer

commands

notes

In Prowlarr, open Indexers, choose Add Indexer, and select Generic Torznab. Set the name to Class 54 Teaching Indexer. Set the URL to http://127.0.0.1:18080. If the form displays a separate API Path field, set it to /api. If it expects the path in the URL instead, use http://127.0.0.1:18080/api. Enter mock-key if the form requires an API key. Leave redirect settings disabled, enable the search modes appropriate to the lab, run Test, and save only after the test succeeds.

step

8

title

Exercise indexer management

commands

notes

Open the saved indexer and inspect its detected categories. Perform an interactive search for Class 54 Test. Confirm that a synthetic result appears. Disable the indexer and observe that it is excluded from normal enabled-indexer operations, then enable it again. Review System, Events and System, Log Files to connect interface actions with operational evidence.

step

9

title

Observe a controlled failure and recover

commands

cd /opt/lab-classroom/class54 && kill "$(cat mock-indexer.pid)"
sleep 2

notes

Run the indexer test again and record the error. This demonstrates a transport failure rather than an authentication or category failure. Restart the teaching indexer with the command from step 5, verify the capabilities URL, and retest the indexer in Prowlarr.