Rephl3x/Magent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(install): cover Docker and native deployments

Browse Source
This commit is contained in:
Magent release tooling
2026-09-20 17:09:14 +12:00
parent 4aba89c063
commit 76b2b8d879
16 changed files with 1141 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/installation-and-recovery.md
+15 -29
View File
@@ -2,42 +2,28 @@
## Fresh installation
For a new Portainer installation without a Dockerfile or `.env`, use the
[single-file stack guide](PORTAINER.md). It generates persistent deployment
secrets and provides a console-only setup-token command. The root stack pulls
`rephl3xnz/magent:latest` with no environment inputs. Confirm the application URL
alongside the token when creating your first administrator; managed CORS and
cookie security follow that URL automatically. SQLite is fixed at
`/app/data/magent.db`, and API documentation remains disabled. Leave the Compose
runtime-security defaults unchanged. The updated image still needs publishing
before `latest` provides this behaviour; repository changes alone do not deploy
or publish it. Record deployed digests because `latest` is mutable.
Choose [Docker Compose/CLI](DOCKER.md), [Portainer](PORTAINER.md),
[native Linux services](NATIVE_INSTALL.md) or [foreground source installation](LOCAL_DEVELOPMENT.md)
from the [installation overview](INSTALLATION.md). Follow that guide for private
configuration, startup, health checks and the correct setup-token command.
The **manual-secret and source-build instructions below** remain supported for
other deployments. All environment options and defaults are documented in
[ENVIRONMENT.md](ENVIRONMENT.md); they are not required inputs to the managed
Portainer template.
The managed container image is published as `rephl3xnz/magent:latest`; its root
Compose file has no environment inputs and retains explicit security defaults.
Managed containers persist generated secrets and confirm their application URL
when creating the first administrator. Native/manual installations instead load
their own private keys, exact URL/CORS and HTTP/HTTPS cookie policy explicitly.
See [ENVIRONMENT.md](ENVIRONMENT.md) for all environment options. Neither mode
configures DNS, installs a reverse proxy or issues TLS certificates.
Start with `.env.example`. Generate independent random values for `JWT_SECRET` and `SETUP_TOKEN` (at least 32 characters each), plus a Fernet `SETTINGS_ENCRYPTION_KEY`. Never deploy the example placeholders. Keep the environment file private.
```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
python -c "import secrets; print(secrets.token_urlsafe(48))"
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```
The first two commands produce the JWT secret and setup token respectively. The third requires the backend dependencies. Alternatively generate the Fernet key using Python's standard library: `python -c "import base64, secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"`.
For a manual-secret installation, set the correct browser-facing `CORS_ALLOW_ORIGIN`, `MAGENT_APPLICATION_URL`, cookie HTTPS settings and host paths before starting. Changing the application URL in its wizard does not replace its explicit environment CORS policy. Managed Portainer installations instead confirm their origin during token-authorized first-admin setup, and automatically follow that saved origin for CORS and cookie security. Neither mode changes reverse-proxy configuration or creates certificates.
After `docker compose -f compose.yml -f compose.build.yml up -d --build` for a source build, visit the frontend. A new database redirects to `/setup`:
Once the selected installation is healthy, visit its frontend. A new database
redirects to `/setup`:
1. Enter `SETUP_TOKEN` and create a local administrator with a unique password of at least 12 characters. Alternatively, set `ADMIN_USERNAME` and `ADMIN_PASSWORD` in the environment before the first start, then sign in with that account.
2. Expand each app you use: Jellyfin, Seerr/Jellyseerr, Sonarr, Radarr, Prowlarr, qBittorrent, Bazarr and Jellystat. Enter its internal address and credentials, then **Save & test**. For Sonarr/Radarr, a successful check loads quality profiles and root folders.
3. Set site access, request refresh/retention and optional SMTP preferences. Invite signup remains invite-only.
4. Review and finish. Magent starts its configured background jobs, unless `BACKGROUND_TASKS_ENABLED=false`.
Use server-reachable addresses: `localhost` in a container refers to that container. Optional apps can be skipped. Each successful save persists; closing the tab leaves setup resumable. Unsaved form fields are not retained. Remove `SETUP_TOKEN` after finishing. Bootstrap is permanently disabled after setup, and cannot replace an existing administrator. Administrators can revisit the wizard from Settings without resetting the installation.
Use server-reachable addresses: `localhost` in a container refers to that container. Optional apps can be skipped. Each successful save persists; closing the tab leaves setup resumable. Unsaved form fields are not retained. Manual/native operators remove the environment `SETUP_TOKEN` after administrator creation and restart the backend. Managed-container operators must not edit/delete their generated secrets file; the console command and bootstrap refuse token reuse after the first administrator exists. Administrators can revisit the wizard from Settings without resetting the installation.
Upgrades with an existing users table are marked configured automatically. Setup status reveals only whether setup is needed and whether the first administrator is missing. Configuration and wizard progress require administrator authentication. First-admin creation uses a constant-time token comparison, persistent rate limits and a database transaction to prevent concurrent claims.
@@ -64,7 +50,7 @@ The frontend and backend accept up to 34 MiB for the whole multipart request, in
1. Make a fresh backup of the destination. Stop external writes/other backend processes sharing its SQLite file. The supplied deployment uses one backend worker; do not run restore against a multi-worker/shared-database deployment.
2. Sign in as an administrator, select a `.magent-backup`, enter its passphrase and type `RESTORE`. A fresh replacement installation must first create its temporary administrator through `/setup`; then use the **Restore it here** link before connecting apps.
3. Upload and stage the restore. Magent checks authentication, encrypted integrity, archive paths and sizes, checksums, SQLite integrity, schema compatibility and an active restored administrator. Live data is unchanged at this point. A pending restore can be cancelled from the same page.
4. Restart the application using your normal deployment process, for example `docker compose restart magent` for a source build, or restart the container in Portainer. The UI never restarts a server automatically.
4. Restart the backend using your installation guide: for the documented Compose project, `docker compose -f compose.yml -p magent restart magent`; for direct Docker, `docker restart magent`; in Portainer, restart its Magent container; for native Linux, `sudo systemctl restart magent-backend.service`. Substitute your actual project/container/unit names. Foreground users stop and relaunch their API process with the same working directory and private environment. The UI never restarts a server automatically.
5. On startup, before schema initialization or workers, Magent creates a private rollback copy, replaces the database/selected assets and records the result. Failed or interrupted replacement is rolled back using a durable journal. Review the backend logs if startup stops.
6. Sign in with an account from the restored backup, verify Settings/service checks, requests, issues and invite policy, then create a new backup. Old sessions and password-reset tokens are invalidated. Existing invite records and links are retained, with their original expiry and usage state.