Throwaway Jellyfin 12.2 for testing the plugin, built and set up by dev/compose.yaml.
Needs only Docker; the dev scripts need Python 3 (standard library only).
docker compose -f dev/compose.yaml up -d # build, set up, start: http://localhost:8096
docker compose -f dev/compose.yaml logs -f # logs (add a service name: plugin, setup, ...)
docker compose -f dev/compose.yaml down # stopRuntime state lives in dev/jellyfin/ (gitignored); stop the instance and delete that folder to
start fresh. Logins, the API key and options live in dev/.env (gitignored).
- plugin: builds the plugin in the .NET SDK image (from a copy of the sources, so the repo
gets no root-owned
bin//obj/) and installs it asJellyLearning_0.0.0.0in Jellyfin's plugins folder, removing any other installed version (dev/build-plugin.sh). - fixtures: generates the test courses from the fixture listings into
dev/jellyfin/courses/(=/data/courses), only when the listings changed (dev/make-fixtures.sh --if-changed). - jellyfin: starts the server once both are done.
- setup (
dev/setup.py) only adds what is missing, so settings made by hand stay:- completes the startup wizard with the admin user
adminand a generated password; - creates an API key for the dev scripts;
- adds the File Transformation plugin repository, installs File Transformation 3.0.3.0 (the course UI needs it) and restarts Jellyfin;
- creates the Shows library Course Fixtures (
/data/courses) and, when real courses are mounted, Courses (/data/elearning), with internet metadata, image fetchers and the NFO saver off (otherwise courses get matched to random TV shows), and ticks them under the plugin's Course libraries; - writes
JELLYFIN_ADMIN_USER/JELLYFIN_ADMIN_PASSWORD,JELLYFIN_API_KEYand the test userJELLYFIN_TEST_USER/JELLYFIN_TEST_PASSWORD(created by the test scripts) todev/.env, keeping whatever else is in it; - starts a library scan.
- completes the startup wizard with the admin user
Every up repeats these steps, so up -d after a code change rebuilds and installs the plugin.
For quick iterations ./dev/deploy.sh does the same and restarts Jellyfin (with the host's
dotnet if there is one, otherwise through the plugin service).
| Variable | Default | |
|---|---|---|
ELEARNING_SOURCE |
none | A folder of real course exports, mounted read-only at /data/elearning; setup adds the "Courses" library for it. |
JELLYFIN_PORT |
8096 |
Host port. |
PUID / PGID |
1000 |
Your user and group (id -u, id -g): the server and setup run as them, and files the build writes are handed to them. |
DEV_STATE |
./jellyfin |
State folder, relative to dev/ (for a second instance, together with docker compose -p <name> and another port). |
Compose reads dev/.env for these, and the dev scripts read it for the logins, so nothing
needs to be exported. Optional by hand: Dashboard → Playback → Resume → Max resume
percentage = 100 (see PLAN.md, Phase 4); the test scripts expect the default 90.
Test courses use invented course and file names, never ones from a real library.
The image is pinned to version-12.2ubu2604 because :latest is already 12.4 and the plugin's
Jellyfin.Controller/Model package versions must match the server. Bump both together.
Don't downgrade an existing config folder; newer servers migrate the database irreversibly.
Run against the running instance; each reads dev/.env itself.
dev/verify-library.py: every course in Jellyfin vs. the parser (exit 1 on mismatch).dev/test-progress.py: the completion rule end to end, as the test user (created if missing). The two long-lecture cases need a real course of 10+ minutes (ELEARNING_SOURCE).dev/test-api.py: the/ELearningAPI end to end (outlines vs. index, files, rendering, security headers, completion, refusals); also creates<test user>-outsiderwithout library access to check access control.dev/test-course-json.py:course.jsonend to end. Checks the fixture that ships one, then walks a mock course through no file → overrides → edit → invalid file → removed, scanning the library after each step (about 3 minutes; it waits out the plugin's 30 s course cache). Removes the mock course unless--keep. To run it without touching your main dev instance, start a second one:DEV_STATE=/abs/path JELLYFIN_PORT=8197 SETUP_ENV_FILE=/state/.env ELEARNING_SOURCE= docker compose -p jl-cj -f dev/compose.yaml up -d, thenDEV_ENV_FILE=/abs/path/.env DEV_STATE=/abs/path JELLYFIN_URL=http://localhost:8197 dev/test-course-json.py.dev/ui-view.py [name]: courses as the web client lists them.dev/library-report.sh [path]: raw Series/Season/Episode rows from the database (needssqlite3).dev/make-fixtures.sh: rebuild the test courses by hand (needsffmpeg). The fixtureSample - Markdown Notesgets acourse.json(seedocs/course-json.md): after a scan it shows as "Markdown Notes (course.json)" with sections "Further" then "Basics" and a first lecture "Hello!".
- Course UI script:
Jellyfin.Plugin.ELearning/Web/elearning.js; after./dev/deploy.shreload the browser tab (the script URL carries a content hash, so no cache clearing is needed). Its console messages start with[JellyLearning]. - Document-lecture progress:
dev/jellyfin/config/data/data/elearning/progress/<user>.json. - Course index written by the plugin after each scan:
dev/jellyfin/config/data/data/elearning/course-index.json. - Generated covers:
dev/jellyfin/config/data/data/elearning/covers/.
To check that both plugins install from manifest.json (the real URL, or a local copy): start a Jellyfin
12.2 container with no plugins, finish its wizard, add the manifest under Dashboard → Plugins →
Repositories (API: POST /Repositories), install File Transformation and JellyLearning from the catalog
(POST /Packages/Installed/<name>?assemblyGuid=…&version=…&repositoryUrl=…), restart, and check
GET /Plugins shows both as Active. Jellyfin needs an MD5 checksum and the plugin files at the zip root.
For a local copy, serve it from a second container on a shared docker network
(python:3.13-slim running python -m http.server, http://<name>:8099/manifest.json): a container here
could not reach a server on the host (host.docker.internal timed out), and Jellyfin then hangs on
GET /Packages until its 100 s timeout.