feat(release): publish minimal self-contained Magent source

2026-09-19 16:58:12 +12:00
commit 5fa5d45535
272 changed files with 79305 additions and 0 deletions
@@ -0,0 +1,103 @@
+# Magent
+
+Self-hosted media requests, viewing stats and issue management for Jellyfin,
+Seerr, Sonarr, Radarr and related services. Magent combines a Python/FastAPI API,
+a Next.js frontend and SQLite in one non-root container.
+
+## Install
+
+Paste [compose.yml](compose.yml) into a Portainer **Docker Standalone** stack.
+It uses `rephl3xnz/magent:latest`, persists data in a named volume and needs no
+environment variables or Dockerfile on the user's machine.
+
+**Image availability:** this source snapshot has not yet been published to
+Docker Hub. The current `latest` image may not include this setup flow. Until a
+compatible image is published, use the source-build command below for testing.
+Only Linux/amd64 has been validated.
+
+1. Deploy the stack and wait for the container to become healthy.
+2. In its console, select `/bin/ash` and user `magent`, then run:
+
+   ```sh
+   python -m app.container_bootstrap setup-token
+   ```
+
+3. Open the Docker host's address on port 3000. Confirm the browser-facing URL
+   in setup and use the token to create the first administrator.
+4. Connect your apps, choose preferences and finish setup. Optional apps can
+   be skipped. Save an encrypted backup afterwards.
+
+Keep the Compose security block unchanged. Database storage is fixed at
+`/app/data/magent.db` and API docs are disabled in managed installs. CORS and
+cookie security follow the confirmed URL. Use HTTPS before public access.
+
+See [Portainer setup](docs/PORTAINER.md),
+[all environment options](docs/ENVIRONMENT.md),
+[backup and restore](docs/installation-and-recovery.md) and
+[advanced installation/upgrades](docs/PUBLIC_RELEASE.md).
+Existing installations must retain their original data volume and signing/
+encryption keys; this fresh-install template is not an automatic migration.
+
+## Build and test
+
+The source tree contains everything needed to build the application:
+
+```sh
+docker compose -f compose.yml -f compose.build.yml up -d --build
+```
+
+For a disposable verification run, without touching an existing installation:
+
+```sh
+docker build -t magent:review .
+bash scripts/ci_container_smoke.sh magent:review
+MAGENT_SMOKE_MANAGED=true bash scripts/ci_container_smoke.sh magent:review
+```
+
+Unit checks require Python 3.14 and Node 24:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+pip install -r backend/requirements-dev.txt
+python -m unittest discover -s backend/tests -p 'test_*.py'
+python scripts/check_environment_docs.py
+cd frontend
+npm ci
+npm test
+npm run lint
+npm run format:check
+npm run typecheck
+```
+
+On Windows, activate `.venv\Scripts\Activate.ps1` instead. Do not point tests
+at live services or use production credentials.
+
+## How it is organised
+
+- `backend/app/routers/`: authenticated API endpoints and administration.
+- `backend/app/clients/`: media-service clients; `services/`: request states,
+  synchronisation, notifications, setup and encrypted backups.
+- `backend/app/db.py` and `schema_migrations.py`: SQLite persistence/migrations.
+- `frontend/app/`: pages and shared interface components; `frontend/proxy.ts`:
+  browser security headers and request nonces.
+- `backend/tests/` and frontend `*.test.*`: synthetic regression tests.
+- `Dockerfile` and `docker/`: multi-stage build and process supervision.
+- `compose.yml`: prebuilt-image install; `compose.build.yml`: source override.
+
+Requests are cached from Seerr, joined to collector/download/library evidence,
+normalised into a user-facing state and displayed by the frontend. App settings
+are stored in SQLite; sensitive settings are encrypted with installation-specific
+keys. Integrations are optional and are configured through the setup wizard.
+
+This `release` branch intentionally excludes internal deployment scripts,
+environment files, runtime data, development reports and prior Git history.
+It contains no workflow that automatically deploys or publishes an image.
+
+## Contributing and security
+
+Keep changes focused, add regression tests and run the checks above. Never
+commit tokens, database exports, backups or real user information.
+See [SECURITY.md](SECURITY.md) for reporting guidance and deployment precautions.
+
+Licensed under [MIT](LICENSE). Third-party dependency licences remain applicable.