# 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.