feat(release): prepare first public preview
This commit is contained in:
Magent release tooling
@@ -1,78 +1,111 @@
|
||||
# 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.
|
||||
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.
|
||||
|
||||
## Install
|
||||
**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)
|
||||
|
||||
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) |
|
||||
Magent does not store or stream media, replace your existing applications, or
|
||||
provide content. You bring and operate those services; Magent connects to them.
|
||||
|
||||
For a fresh **Docker Compose** install, download [compose.yml](compose.yml) into
|
||||
its own deployment directory and run:
|
||||
## 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 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.
|
||||
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.
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
||||
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.
|
||||
For public access, configure DNS and HTTPS before creating the administrator.
|
||||
Do not forward the plain HTTP port directly to the internet.
|
||||
|
||||
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.
|
||||
## Other installation methods
|
||||
|
||||
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.
|
||||
| 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) |
|
||||
|
||||
## Build and test
|
||||
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.
|
||||
|
||||
The source tree contains everything needed to build the application:
|
||||
### 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
|
||||
```
|
||||
|
||||
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:
|
||||
The full quality gate uses Python 3.14 and Node.js 24:
|
||||
|
||||
```sh
|
||||
python -m venv .venv
|
||||
@@ -86,37 +119,37 @@ npm test
|
||||
npm run lint
|
||||
npm run format:check
|
||||
npm run typecheck
|
||||
npm run build
|
||||
```
|
||||
|
||||
On Windows, activate `.venv\Scripts\Activate.ps1` instead. Do not point tests
|
||||
at live services or use production credentials.
|
||||
On Windows, use `.venv\Scripts\Activate.ps1`. Tests must use synthetic data and
|
||||
must never point at live media services.
|
||||
|
||||
## How it is organised
|
||||
## Project layout
|
||||
|
||||
- `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/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.
|
||||
- `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.
|
||||
- `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.
|
||||
|
||||
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.
|
||||
The `release` branch is a deliberately small public export. It excludes private
|
||||
deployment automation, credentials, runtime data and internal Git history.
|
||||
|
||||
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.
|
||||
## Help, feedback and contributions
|
||||
|
||||
## Contributing and security
|
||||
- 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).
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Licensed under [MIT](LICENSE). Third-party dependency licences remain applicable.
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user