105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# 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:** the managed-install image is published on Docker Hub.
|
|
Only Linux/amd64 has been validated. `latest` is mutable; record the resolved
|
|
image digest before updating, or pin an immutable release tag.
|
|
|
|
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.
|
|
The **Get setup token** button shows the console instructions and lets you
|
|
copy the command; it never reveals the token to public visitors.
|
|
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.
|