156 lines
7.0 KiB
Markdown
156 lines
7.0 KiB
Markdown
# Magent
|
|
|
|
Magent is a self-hosted home for media requests, viewing insights and issue
|
|
follow-up. It sits in front of Jellyfin, Seerr, Sonarr, Radarr and related apps,
|
|
then turns their technical state into a clearer experience for the people using
|
|
your server.
|
|
|
|
**Public preview:** `0.1.0-preview.1` · [Source code](https://git.amslabs.net/Rephl3x/Magent-Public) ·
|
|
[Docker Hub](https://hub.docker.com/r/rephl3xnz/magent) · [MIT license](LICENSE)
|
|
|
|
|
|
|
|
Magent does not store or stream media, replace your existing applications, or
|
|
provide content. You bring and operate those services; Magent connects to them.
|
|
|
|
## Why Magent?
|
|
|
|
Media automation is powerful, but its status messages are written for operators.
|
|
Magent gives users one place to request something, understand what is happening,
|
|
see when it is ready, report a problem and follow the response.
|
|
|
|
- Search for and submit movie or TV requests through Seerr.
|
|
- Follow a request across approval, Arr monitoring, download and Jellyfin availability.
|
|
- Open ready titles in Jellyfin and report playback or library problems.
|
|
- View private Jellystat-powered viewing insights and monthly reports.
|
|
- Offer local or Jellyfin sign-in, invite-only registration and per-user features.
|
|
- Manage integrations, users, branding, notifications and diagnostics from the UI.
|
|
- Export an encrypted backup of configuration, SQLite data and optional artwork.
|
|
|
|
## Current scope
|
|
|
|
- The published container is validated on **Linux/amd64**.
|
|
- Magent is a single-instance application using one writable SQLite database. It
|
|
is not an HA, Kubernetes or multi-replica deployment.
|
|
- Native Windows foreground operation has been smoke-tested. Linux systemd files
|
|
are statically validated; macOS instructions are reviewed but not runtime-tested.
|
|
- This is an early public release. Pin an immutable image tag or digest, retain
|
|
backups, and test upgrades before using them on your main instance.
|
|
|
|
See [release notes](CHANGELOG.md) and [installation support boundaries](docs/INSTALLATION.md#platform-and-support-boundaries).
|
|
|
|
## Quick start with Docker Compose
|
|
|
|
Docker Compose is the recommended first installation. Create an empty directory,
|
|
download the public Compose file, and start Magent:
|
|
|
|
```sh
|
|
curl --fail --location --output compose.yml \
|
|
https://git.amslabs.net/Rephl3x/Magent-Public/raw/branch/release/compose.yml
|
|
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 exec --user magent magent \
|
|
python -m app.container_bootstrap setup-token
|
|
```
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
Invoke-WebRequest -Uri 'https://git.amslabs.net/Rephl3x/Magent-Public/raw/branch/release/compose.yml' -OutFile compose.yml
|
|
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 exec --user magent magent python -m app.container_bootstrap setup-token
|
|
```
|
|
|
|
Open `http://SERVER_IP:3000/setup`, enter the console-only token and confirm the
|
|
browser-facing URL. Then create the first administrator and connect the apps you
|
|
use. Optional integrations can be skipped. The managed image creates and retains
|
|
its own private keys; this path needs no `.env` or Dockerfile.
|
|
|
|
If you cloned the repository, the optional helper exposes the same operations:
|
|
`./setup.sh check`, `./setup.sh install`, and `./setup.sh token`. Read a script
|
|
before running it; the documented Compose commands remain the canonical path.
|
|
|
|
For public access, configure DNS and HTTPS before creating the administrator.
|
|
Do not forward the plain HTTP port directly to the internet.
|
|
|
|
## Other installation methods
|
|
|
|
| Method | Guide |
|
|
| --- | --- |
|
|
| Docker Compose | [Complete Docker guide](docs/DOCKER.md#docker-compose) |
|
|
| Docker CLI without Compose | [`docker run` guide](docs/DOCKER.md#docker-cli-without-compose) |
|
|
| Portainer | [Paste-and-deploy stack](docs/PORTAINER.md) |
|
|
| Build the container from source | [Source-build override](docs/DOCKER.md#build-the-container-from-source) |
|
|
| Native Linux | [Python/Node and systemd](docs/NATIVE_INSTALL.md) |
|
|
| Windows, macOS or Linux foreground | [Local/source installation](docs/LOCAL_DEVELOPMENT.md) |
|
|
|
|
Start with the [installation overview](docs/INSTALLATION.md) if you are unsure.
|
|
The [environment reference](docs/ENVIRONMENT.md) documents every supported
|
|
variable, while [backup and recovery](docs/installation-and-recovery.md) covers
|
|
portable exports, offline snapshots and safe restore.
|
|
|
|
### Existing installations
|
|
|
|
Keep the same Compose project name, data mount and signing/encryption keys. The
|
|
fresh-install named volume is not an automatic migration of an existing bind
|
|
mount. Record your working image digest and make an encrypted backup before an
|
|
upgrade. Never use `docker compose down -v` on data you want to keep.
|
|
|
|
## Build and test from source
|
|
|
|
```sh
|
|
git clone --branch release --single-branch https://git.amslabs.net/Rephl3x/Magent-Public.git
|
|
cd Magent-Public
|
|
docker compose -f compose.yml -f compose.build.yml -p magent up -d --build
|
|
```
|
|
|
|
The full quality gate uses Python 3.14 and Node.js 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
|
|
npm run build
|
|
```
|
|
|
|
On Windows, use `.venv\Scripts\Activate.ps1`. Tests must use synthetic data and
|
|
must never point at live media services.
|
|
|
|
## Project layout
|
|
|
|
- `backend/app/`: FastAPI routes, service clients, request state, authentication,
|
|
setup, notifications and encrypted backups.
|
|
- `frontend/app/`: Next.js pages, shared UI, account portal and administration.
|
|
- `backend/tests/` and frontend `*.test.*`: synthetic regression tests.
|
|
- `compose.yml`: prebuilt-image install; `compose.build.yml`: source-build override.
|
|
- `deploy/native/`: example Linux service units and private configuration templates.
|
|
- `docs/`: installation, environment, HTTPS, backup, upgrade and rollback guidance.
|
|
|
|
The `release` branch is a deliberately small public export. It excludes private
|
|
deployment automation, credentials, runtime data and internal Git history.
|
|
|
|
## Help, feedback and contributions
|
|
|
|
- Read [SUPPORT.md](SUPPORT.md) before opening an installation or bug report.
|
|
- See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull-request checks.
|
|
- Report security concerns using [SECURITY.md](SECURITY.md); never post secrets or
|
|
exploit details in a public issue.
|
|
- Community participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
|
|
|
Magent was developed through an iterative, AI-assisted workflow and then checked
|
|
with automated regression tests, isolated container smoke tests and a sanitized
|
|
public-release pass. Treat generated code like any other code: inspect it, test
|
|
it and report anything that does not make sense.
|
|
|
|
Magent is licensed under the [MIT License](LICENSE). Dependencies and base-image
|
|
components retain their own licenses; see [third-party notices](THIRD_PARTY_NOTICES.md).
|