182 lines
5.1 KiB
Markdown
182 lines
5.1 KiB
Markdown
# Magent
|
|
|
|
Magent is a friendly, AI-assisted request tracker for Jellyseerr + 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 Jellyseerr 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 Jellyseerr, 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".
|
|
- Docker-first deployment for easy hosting.
|
|
|
|
## 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) Create `.env` with your service URLs and API keys.
|
|
2) Run `docker compose up --build`.
|
|
3) Log in at http://localhost:3000.
|
|
4) Visit Settings to confirm service health.
|
|
|
|
### Gravitee APIM (optional)
|
|
|
|
If you want API management in front of Magent, you can run the Gravitee stack alongside
|
|
the main container:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml -f docker-compose.gravitee.yml up -d
|
|
```
|
|
|
|
Then open the Management UI at http://localhost:8084 and create a new API that points to
|
|
`http://magent:8000`. The Gravitee gateway will be available at http://localhost:8082.
|
|
|
|
### 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="change-me"
|
|
JWT_EXP_MINUTES="720"
|
|
ADMIN_USERNAME="admin"
|
|
ADMIN_PASSWORD="adminadmin"
|
|
```
|
|
|
|
## 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="change-me"
|
|
$env:JWT_EXP_MINUTES="720"
|
|
$env:ADMIN_USERNAME="admin"
|
|
$env:ADMIN_PASSWORD="adminadmin"
|
|
```
|
|
|
|
### 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).
|
|
|
|
## 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.
|
|
|
|
## History endpoints
|
|
|
|
- `GET /requests/{id}/history?limit=10` recent snapshots
|
|
- `GET /requests/{id}/actions?limit=10` recent action logs
|
|
|
|
## Troubleshooting
|
|
|
|
### Login fails
|
|
|
|
- Make sure `ADMIN_USERNAME` and `ADMIN_PASSWORD` are set in `.env`.
|
|
- 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 Jellyseerr 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.
|