Hands-on 01-jellyseerr-or-overseerr-request-management: Lab

scope

All created or modified filesystem content is confined to /opt/lab-classroom/class56/. The exercise does not start containers, contact TMDB, or modify a production service.

steps

step

1

title

Create the isolated workspace

instructions

Create directories for the Compose project and its future application configuration.

commands

mkdir -p /opt/lab-classroom/class56/config

step

2

title

Create and inspect the Compose model

instructions

Write the following content to /opt/lab-classroom/class56/compose.yaml. The loopback port prevents direct LAN exposure, and the persistent path remains inside the class workspace.

file

/opt/lab-classroom/class56/compose.yaml

content

services:
jellyseerr:
image: ${JELLYSEERR_IMAGE:?JELLYSEERR_IMAGE must be set}
restart: unless-stopped
environment:
TZ: ${TZ:?TZ must be set}
LOG_LEVEL: info
ports:
- "127.0.0.1:5055:5055"
volumes:
- /opt/lab-classroom/class56/config:/app/config

step

3

title

Provide non-secret Compose interpolation values

instructions

Write the following content to /opt/lab-classroom/class56/.env.example. This file intentionally contains no TMDB, media-server, automation, or webhook credential.

file

/opt/lab-classroom/class56/.env.example

content

JELLYSEERR_IMAGE=ghcr.io/fallenbagel/jellyseerr:latest
TZ=Etc/UTC

step

4

title

Validate the Docker Compose definition

instructions

If Docker Compose v2 is installed, render the effective model. This validates interpolation and YAML structure without starting a container. If Docker Compose is unavailable, record that limitation and manually inspect the bind address, volume path, image interpolation, and environment interpolation.

commands

cd /opt/lab-classroom/class56 && docker compose --env-file .env.example config

success_conditions

The rendered service uses the Jellyseerr image reference supplied by .env.example.
The published address is 127.0.0.1:5055 rather than an all-interface binding.
The only host volume path is /opt/lab-classroom/class56/config.
No credential appears in compose.yaml or .env.example.

step

5

title

Create the intentionally unsafe policy

instructions

Write the following policy to /opt/lab-classroom/class56/request-policy.json. Do not repair it yet. It is intentionally unacceptable and exists to prove that the validator rejects unsafe settings.

file

/opt/lab-classroom/class56/request-policy.json

content

{
"approval": {
"manual_required": false,
"auto_approve": true
},
"roles": {
"default": "administrator",
"synced_user_role": "administrator"
},
"limits": {
"weekly_requests": 0
},
"integrations": {
"tmdb": {
"api_key_source": "missing"
},
"media_server": {
"user_sync": false
}
},
"availability": {
"sync_marks_existing": true,
"triggers_library_scan": true
},
"secrets_inline": true
}

step

6

title

Create the policy validator

instructions

Write the following Python program to /opt/lab-classroom/class56/validate_policy.py. The validator reports every failed control and exits nonzero when any control fails.

file

/opt/lab-classroom/class56/validate_policy.py

content

import json
import pathlib
import sys

path = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else "/opt/lab-classroom/class56/request-policy.json")
try:
policy = json.loads(path.read_text(encoding="utf-8"))
except Exception as exc:
print(f"FAIL: cannot parse {path}: {exc}")
raise SystemExit(2)

checks = [
(policy.get("approval", {}).get("manual_required") is True, "manual approval must be required"),
(policy.get("approval", {}).get("auto_approve") is False, "automatic approval must be disabled"),
(policy.get("roles", {}).get("default") == "requester", "default role must be requester"),
(policy.get("roles", {}).get("synced_user_role") == "requester", "synchronized users must default to requester"),
(isinstance(policy.get("limits", {}).get("weekly_requests"), int) and not isinstance(policy.get("limits", {}).get("weekly_requests"), bool) and 1 <= policy.get("limits", {}).get("weekly_requests") <= 10, "weekly request limit must be an integer from 1 through 10"),
(policy.get("integrations", {}).get("tmdb", {}).get("api_key_source") == "env:TMDB_API_KEY", "TMDB credential source must be env:TMDB_API_KEY"),
(policy.get("integrations", {}).get("media_server", {}).get("user_sync") is True, "media-server user synchronization must be enabled"),
(policy.get("availability", {}).get("sync_marks_existing") is True, "availability synchronization must mark existing media"),
(policy.get("availability", {}).get("triggers_library_scan") is False, "availability synchronization must not be treated as a library-scan trigger"),
(policy.get("secrets_inline") is False, "inline secrets must be prohibited")
]

failures = [message for passed, message in checks if not passed]
if failures:
for message in failures:
print(f"FAIL: {message}")
print(f"RESULT: rejected with {len(failures)} policy violation(s)")
raise SystemExit(1)

print("PASS: policy satisfies all classroom controls")

step

7

title

Prove the unsafe policy fails

instructions

Run the validator through a shell condition that treats rejection as the expected result. This is the required negative test.

commands

cd /opt/lab-classroom/class56 && if python3 validate_policy.py request-policy.json; then echo 'UNEXPECTED: unsafe policy passed'; exit 1; else echo 'EXPECTED: unsafe policy was rejected'; fi

success_conditions

The validator prints one or more FAIL lines.
The shell prints EXPECTED: unsafe policy was rejected.
The unsafe policy is not mistaken for a deployable configuration.

step

8

title

Repair the policy without copying a golden document

instructions

Edit /opt/lab-classroom/class56/request-policy.json using an editor available in the classroom. Require manual approval, disable automatic approval, assign requester as both the default and synchronized-user role, choose an integer weekly request limit from 1 through 10, set the TMDB credential source to env:TMDB_API_KEY, enable media-server user synchronization, retain availability marking, disable library-scan triggering, and prohibit inline secrets. The range intentionally permits an operator policy decision rather than one fixed answer.

required_controls

approval.manual_required is true
approval.auto_approve is false
roles.default is requester
roles.synced_user_role is requester
limits.weekly_requests is an integer from 1 through 10
integrations.tmdb.api_key_source is env:TMDB_API_KEY
integrations.media_server.user_sync is true
availability.sync_marks_existing is true
availability.triggers_library_scan is false
secrets_inline is false

step

9

title

Validate the repaired policy

instructions

Run the validator again. Do not continue until it returns exit status zero.

commands

cd /opt/lab-classroom/class56 && python3 validate_policy.py request-policy.json
cd /opt/lab-classroom/class56 && python3 -m json.tool request-policy.json >/dev/null

success_conditions

The validator prints PASS: policy satisfies all classroom controls.
The JSON parser exits successfully.
No actual API credential has been written into the policy.

step

10

title

Review first-run operational gates

instructions

Before any later deployment, document that a legitimate TMDB credential must be supplied through the supported secret mechanism, the media-server URL and token must be tested, synchronized users must be reviewed for role assignment, libraries must be selected, and availability synchronization must not be confused with the media server's scan operation. Do not place real credentials in the class directory.