238 lines
11 KiB
Markdown
238 lines
11 KiB
Markdown
# Magent
|
|
|
|
Magent is a friendly, AI-assisted request tracker for Seerr + Arr services. It shows a clear timeline of where a request is stuck, explains what is happening in plain English, and offers safe actions to help fix issues.
|
|
|
|
## How it works
|
|
|
|
1) Requests are pulled from Seerr and stored locally.
|
|
2) Magent joins that request to Sonarr/Radarr, Prowlarr, qBittorrent, and Jellyfin using TMDB/TVDB IDs and download hashes.
|
|
3) A state engine normalizes noisy service statuses into a simple, user-friendly state.
|
|
4) The UI renders a timeline and a central status box for each request.
|
|
5) Optional AI triage summarizes the likely cause and safest next steps.
|
|
|
|
## Core features
|
|
|
|
- Request search by title/year or request ID.
|
|
- Recent requests list with posters and status.
|
|
- Timeline view across Seerr, Arr, Prowlarr, qBittorrent, Jellyfin.
|
|
- Central status box with clear reason + next steps.
|
|
- Safe action buttons (search, resume, re-add, etc.).
|
|
- Admin settings for service URLs, API keys, profiles, and root folders.
|
|
- Health status for each service in the pipeline.
|
|
- Cache and sync controls (full sync, delta sync, scheduled syncs).
|
|
- Local database for speed and audit history.
|
|
- Users and access control (admin vs user, block access).
|
|
- Local account password changes via "My profile".
|
|
- Personal viewing stats from Jellystat: minutes, movies, episodes, streaks, and recent plays alongside requests. See [Jellystat setup](docs/jellystat-integration.md).
|
|
- Admin review and confirmation of account IDs across Jellyfin, Seerr, Jellystat and Magent. See [user identities](docs/user-identities.md).
|
|
- Docker-first deployment for easy hosting.
|
|
- Guided, resumable first-install setup with app connection tests.
|
|
- Encrypted backups of configuration, database and optional artwork cache, with restart-only restore.
|
|
|
|
## Quick start (Docker - primary)
|
|
|
|
Docker is the recommended way to run Magent. It includes the backend and frontend with sane defaults.
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
Then open:
|
|
|
|
- Frontend: http://localhost:3000
|
|
- Backend: http://localhost:8000
|
|
|
|
### Docker setup steps
|
|
|
|
1) Copy `.env.example` to `.env`. Generate independent `JWT_SECRET`, `SETTINGS_ENCRYPTION_KEY` and `SETUP_TOKEN` values as described below. Do not use the example placeholders.
|
|
2) Set `CORS_ALLOW_ORIGIN` and `MAGENT_APPLICATION_URL` to your browser-facing origin. For public deployments, use HTTPS and `AUTH_COOKIE_SECURE=true`.
|
|
3) Run `docker compose up --build`.
|
|
4) Open http://localhost:3000. A fresh database opens the setup wizard automatically. Use your `SETUP_TOKEN` to create a local administrator, then connect and test each app you use.
|
|
5) Choose site, sign-in, request-sync and email preferences, review the connections, and finish setup. Remove `SETUP_TOKEN` from the deployment environment afterwards.
|
|
|
|
Apps may be skipped and configured later. Progress is saved in SQLite. Background imports and automation remain paused until setup is complete; `BACKGROUND_TASKS_ENABLED=false` still takes precedence. Existing installations are automatically treated as configured and are not forced through the wizard. Administrators can reopen it at **Settings → Advanced tools → Setup wizard**.
|
|
|
|
If you prefer to seed an administrator through deployment configuration, set a unique `ADMIN_USERNAME` and `ADMIN_PASSWORD` instead of `SETUP_TOKEN`. The wizard then asks you to sign in with that account. Environment credentials create only the first administrator; they do not add another account to a restored installation. Service URLs and API keys can still be supplied through the environment, and the wizard preloads these settings without exposing saved secrets.
|
|
|
|
See [installation and recovery](docs/installation-and-recovery.md) for migration, backup limits and restore instructions.
|
|
|
|
### Docker environment variables (sample)
|
|
|
|
```bash
|
|
JELLYSEERR_URL="http://localhost:5055"
|
|
JELLYSEERR_API_KEY="..."
|
|
SONARR_URL="http://localhost:8989"
|
|
SONARR_API_KEY="..."
|
|
SONARR_QUALITY_PROFILE_ID="1"
|
|
SONARR_ROOT_FOLDER="/tv"
|
|
RADARR_URL="http://localhost:7878"
|
|
RADARR_API_KEY="..."
|
|
RADARR_QUALITY_PROFILE_ID="1"
|
|
RADARR_ROOT_FOLDER="/movies"
|
|
PROWLARR_URL="http://localhost:9696"
|
|
PROWLARR_API_KEY="..."
|
|
QBIT_URL="http://localhost:8080"
|
|
QBIT_USERNAME="..."
|
|
QBIT_PASSWORD="..."
|
|
SQLITE_PATH="data/magent.db"
|
|
JWT_SECRET="replace-with-at-least-32-random-characters"
|
|
SETTINGS_ENCRYPTION_KEY="replace-with-a-fernet-key"
|
|
JWT_EXP_MINUTES="120"
|
|
ADMIN_USERNAME="set-a-real-admin-username"
|
|
ADMIN_PASSWORD="set-a-long-unique-admin-password"
|
|
```
|
|
|
|
## Screenshots
|
|
|
|
Add screenshots here once available:
|
|
|
|
- `docs/screenshots/home.png`
|
|
- `docs/screenshots/request-timeline.png`
|
|
- `docs/screenshots/settings.png`
|
|
- `docs/screenshots/profile.png`
|
|
|
|
## Local development (secondary)
|
|
|
|
Use this only when you need to modify code locally.
|
|
|
|
### Backend (FastAPI)
|
|
|
|
```bash
|
|
cd backend
|
|
python -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
pip install -r requirements.txt
|
|
uvicorn app.main:app --reload --port 8000
|
|
```
|
|
|
|
Environment variables (sample):
|
|
|
|
```bash
|
|
$env:JELLYSEERR_URL="http://localhost:5055"
|
|
$env:JELLYSEERR_API_KEY="..."
|
|
$env:SONARR_URL="http://localhost:8989"
|
|
$env:SONARR_API_KEY="..."
|
|
$env:SONARR_QUALITY_PROFILE_ID="1"
|
|
$env:SONARR_ROOT_FOLDER="/tv"
|
|
$env:RADARR_URL="http://localhost:7878"
|
|
$env:RADARR_API_KEY="..."
|
|
$env:RADARR_QUALITY_PROFILE_ID="1"
|
|
$env:RADARR_ROOT_FOLDER="/movies"
|
|
$env:PROWLARR_URL="http://localhost:9696"
|
|
$env:PROWLARR_API_KEY="..."
|
|
$env:QBIT_URL="http://localhost:8080"
|
|
$env:QBIT_USERNAME="..."
|
|
$env:QBIT_PASSWORD="..."
|
|
$env:SQLITE_PATH="data/magent.db"
|
|
$env:JWT_SECRET="replace-with-at-least-32-random-characters"
|
|
$env:SETTINGS_ENCRYPTION_KEY="replace-with-a-fernet-key"
|
|
$env:JWT_EXP_MINUTES="120"
|
|
$env:ADMIN_USERNAME="set-a-real-admin-username"
|
|
$env:ADMIN_PASSWORD="set-a-long-unique-admin-password"
|
|
```
|
|
|
|
### Frontend (Next.js)
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Open http://localhost:3000
|
|
|
|
Admin panel: http://localhost:3000/admin
|
|
|
|
Login uses the admin credentials above (or any other local user you create in SQLite).
|
|
|
|
### Local quality checks
|
|
|
|
```bash
|
|
bash scripts/ci_backend_quality_gate.sh
|
|
cd frontend
|
|
npm ci
|
|
npm run lint
|
|
npm run format:check
|
|
npm run typecheck
|
|
npm test
|
|
npm run build
|
|
```
|
|
|
|
## Public Hosting Notes
|
|
|
|
The frontend proxies `/api/*` to the backend container. Set:
|
|
|
|
- `NEXT_PUBLIC_API_BASE=/api` (browser uses same-origin)
|
|
- `BACKEND_INTERNAL_URL=http://backend:8000` (container-to-container)
|
|
|
|
If you prefer the browser to call the backend directly, set `NEXT_PUBLIC_API_BASE` to your public backend URL and ensure CORS is configured.
|
|
|
|
## Gitea CI/CD
|
|
|
|
This repo now includes a Gitea Actions workflow at `.gitea/workflows/ci-cd.yml`.
|
|
|
|
- Push to `beta`: runs the complete quality gate and deploys the isolated beta environment to `AMS-DEV01`.
|
|
- Push to `main` or `prod`: runs the same verification without automatically changing production.
|
|
- Production releases are tagged from `main` and deployed to `GRZ-DKR01` using the checklist in `PRODUCTION.md`.
|
|
|
|
The beta deploy step ships tracked repository files over SSH, preserves beta's own `.env` and `data/`, rebuilds with `docker compose up -d --build`, and smoke-tests:
|
|
|
|
- `http://127.0.0.1:8000/health`
|
|
- `http://127.0.0.1:3000/login`
|
|
|
|
Configure these Gitea Actions secrets before enabling the deploy job:
|
|
|
|
The existing `PROD_*` names are retained for compatibility, but this workflow uses them only for the isolated beta host deployment.
|
|
|
|
- `PROD_SSH_PRIVATE_KEY`: private key for the deployment account.
|
|
- `PROD_SSH_HOST`: target host, for example `AMS-DEV01`.
|
|
- `PROD_SSH_USER`: target user, for example `zak`.
|
|
- `PROD_SSH_KNOWN_HOSTS`: required pinned `known_hosts` entry. Deployments reject unknown or changed hosts.
|
|
|
|
Beta always deploys to the isolated `/home/<deployment-user>/magent-beta` directory; the production path secret is intentionally ignored.
|
|
|
|
## Security and data handling
|
|
|
|
Generate independent signing and settings-encryption secrets before first startup:
|
|
|
|
```bash
|
|
python -c "import secrets; print(secrets.token_urlsafe(48))"
|
|
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
|
```
|
|
|
|
- `JWT_SECRET` must contain at least 32 characters. Access sessions expire after 120 minutes by default and are revoked after logout, password, role, or blocked-state changes.
|
|
- `SETUP_TOKEN` is a separate random value of at least 32 characters, generated using the first command above a second time. It only authorizes first-admin creation on an unfinished, fresh installation. Never put it in a URL or share it with ordinary users. After completion the public bootstrap endpoint remains disabled even if the token is retained.
|
|
- `SETTINGS_ENCRYPTION_KEY` protects service API keys, SMTP credentials, webhooks, and private keys stored in SQLite. Keep it in `.env`, outside the database and its backups. If omitted, Magent derives a migration-compatible key from `JWT_SECRET`; a dedicated key is recommended.
|
|
- Invite secrets are stored as one-way hashes. Existing invite links continue to work after migration, but the admin UI cannot reveal an old link. Copy a link when it is created, or generate a replacement link later; replacement immediately invalidates the prior link.
|
|
- Magent encrypts sensitive settings, not the entire SQLite database. Request metadata, account records, logs, the `data/` volume, and backups should live on encrypted host storage with access restricted to the deployment account.
|
|
- `REQUESTS_CLEANUP_DAYS` controls routine request-history retention (90 days by default). Account deletion removes authentication and subscription records and anonymizes retained request and portal history.
|
|
- Production and beta cookies require HTTPS and use `SameSite=Strict`. Keep the backend port bound to loopback and publish the frontend only through the intended reverse proxy.
|
|
- **View as user** is a per-tab interface preview: it hides configuration, user-management pages, diagnostics and moderation tools, including direct admin-page URLs. **Exit user view** restores the administrator interface. It does not impersonate another account or change backend permissions; the displayed data still belongs to the signed-in account. Test real permission boundaries with a separate non-admin account.
|
|
|
|
## History endpoints
|
|
|
|
- `GET /requests/{id}/history?limit=10` recent snapshots
|
|
- `GET /requests/{id}/actions?limit=10` recent action logs
|
|
|
|
## Troubleshooting
|
|
|
|
### Login fails
|
|
|
|
- For a fresh installation, open `/setup` and use `SETUP_TOKEN`, or sign in with the environment-seeded administrator. Existing installations use the accounts already in the database; changing `ADMIN_PASSWORD` does not reset an existing account.
|
|
- Confirm the backend is reachable: `http://localhost:8000/health` (or see container logs).
|
|
|
|
### Services show as down
|
|
|
|
- Check the URLs and API keys in Settings.
|
|
- Verify containers can reach each service (network/DNS).
|
|
|
|
### No recent requests
|
|
|
|
- Confirm Seerr credentials in Settings.
|
|
- Run a full sync from Settings -> Requests.
|
|
|
|
### Docker images not updating
|
|
|
|
- Run `docker compose up --build` again.
|
|
- If needed, run `docker compose down` first, then rebuild.
|