123 lines
5.3 KiB
Markdown
123 lines
5.3 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. Run the prebuilt non-root container or install
|
|
the Python and Node.js services directly—Portainer is optional.
|
|
|
|
## Install
|
|
|
|
Start with the [installation guide](docs/INSTALLATION.md) to choose a method:
|
|
|
|
| Method | Instructions |
|
|
| --- | --- |
|
|
| Docker Compose or `docker run` | [Docker installation](docs/DOCKER.md) |
|
|
| Portainer | [Single-file stack](docs/PORTAINER.md) |
|
|
| Linux without Docker | [Native install and systemd services](docs/NATIVE_INSTALL.md) |
|
|
| Windows/macOS/Linux foreground | [Source installation and development](docs/LOCAL_DEVELOPMENT.md) |
|
|
|
|
For a fresh **Docker Compose** install, download [compose.yml](compose.yml) into
|
|
its own deployment directory and run:
|
|
|
|
```sh
|
|
docker compose -f compose.yml -p magent pull
|
|
docker compose -f compose.yml -p magent up -d --wait --wait-timeout 120
|
|
docker compose -f compose.yml -p magent ps
|
|
docker compose -f compose.yml -p magent exec --user magent magent python -m app.container_bootstrap setup-token
|
|
```
|
|
|
|
Keep that directory/project name and its persistent volume unchanged for updates.
|
|
This uses `rephl3xnz/magent:latest` with no environment variables, local source
|
|
build or Dockerfile. Portainer users can paste the same file into a Docker
|
|
Standalone stack instead. Native users follow their separate guide for explicit
|
|
environment configuration and service management.
|
|
|
|
**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. Wait for the container to become healthy and retrieve the token using the
|
|
command above (or the Portainer console instructions in its guide).
|
|
2. 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.
|
|
3. 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 [all installation methods](docs/INSTALLATION.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 -p magent 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.
|
|
- `deploy/native/`: example Linux service units and backend/frontend configuration.
|
|
|
|
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.
|