scormhost

Version 0.1.0 — Turn FastAPI into a SCORM 1.2 / 2004 hosting app with user accounts, JWT auth, and an admin UI — deployable to FastAPI Cloud.

Works with packages built by LXPack (lxpack build --target scorm12 / scorm2004) and other compliant SCORM ZIPs.

Features

• User management — SQLite database, Alembic migrations, bcrypt passwords
• JWT auth — access + refresh tokens (httpOnly cookies for the browser UI, Authorization: Bearer for API clients)
• Public learning — anyone can browse and launch courses without logging in
• Optional login for learners — progress saved to your account when signed in
• Anonymous progress — guests get a browser cookie so progress persists on that device
• Staff login — upload/delete courses and manage users (instructor/admin)
• Roles — learner, instructor, admin (first registered user becomes admin)

Quick start

git clone https://github.com/eddiethedean/scormhost.git
cd scormhost
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# optional: run migrations manually (also runs on startup by default)
alembic upgrade head

fastapi dev

1. Open http://127.0.0.1:8000 — launch any course without an account.
2. Register at /register (first user = admin) to upload SCORM ZIPs or save progress to your account.

Or use the factory:

from scormhost import create_scorm_app

app = create_scorm_app(
    data_dir="./data",
    title="My SCORM Host",
    secret_key="change-me-in-production",
)

Set require_auth=True only if you want to force login before taking courses (not the default).

Database & migrations

Default database: sqlite:///<data_dir>/scormhost.db (override with SCORMHOST_DATABASE_URL).

alembic upgrade head    # apply migrations
alembic revision -m "describe change" --autogenerate  # new revision

On app startup, migrations run automatically when SCORMHOST_AUTO_MIGRATE=true (default).

Roles

Without login: launch courses; progress stored under a guest cookie on this browser.

With login: same, but SCORM progress is keyed to your user id (works across browsers/devices).

Auth API

HTML: /login, /register, /admin/users

SCORM API

Environment variables

Deploy to FastAPI Cloud

cd examples/cloud
pip install -r requirements.txt
fastapi login
fastapi deploy

Set SCORMHOST_DATA_DIR, SCORMHOST_SECRET_KEY, and SCORMHOST_COOKIE_SECURE=true in the dashboard. Always set a stable SCORMHOST_SECRET_KEY in production (do not rely on the random per-start default).

Development

pip install -e ".[dev]"
ruff format .
ruff check .
ty check
pytest

Tests use require_auth=False for SCORM flows and a separate DB for auth tests. Migrations live in src/scormhost/alembic/ and ship inside the wheel; alembic upgrade head from the repo root uses alembic.ini.

Releasing

1. Ensure pyproject.toml and CHANGELOG.md match the target version.
2. Run pytest, ruff check, ty check, and python -m build.
3. Tag v0.1.0 and publish the GitHub release (attach dist/* artifacts if publishing to PyPI manually).

Limits (v0.1)

• SQLite by default (swap SCORMHOST_DATABASE_URL for Postgres in production)
• Package files remain on disk (not in the DB)
• cmi5 / xAPI launch not supported
• SCORM 2004 sequencing not enforced server-side

License

Apache-2.0 — see LICENSE.