docs(install): cover Docker and native deployments
This commit is contained in:
Magent release tooling
@@ -0,0 +1,146 @@
|
||||
# Choose your installation method
|
||||
|
||||
Magent does not require Portainer. It runs either as one prebuilt Linux container
|
||||
or as a Python API plus a Node.js frontend installed directly on your machine.
|
||||
All methods use SQLite, the same setup wizard and the same backup/restore UI.
|
||||
They do not install Jellyfin, Seerr, Sonarr or any of your other media services.
|
||||
|
||||
| Your situation | Guide | What you install/manage |
|
||||
| --- | --- | --- |
|
||||
| Docker Engine with a terminal | [Docker Compose](DOCKER.md#docker-compose) | Recommended container path; no source build or environment inputs |
|
||||
| Docker without Compose | [Docker CLI](DOCKER.md#docker-cli-without-compose) | One `docker run` command, persistent named volume and explicit security flags |
|
||||
| You already use Portainer | [Portainer](PORTAINER.md) | Paste `compose.yml` into a Docker Standalone stack |
|
||||
| You want to build your own container | [Docker source build](DOCKER.md#build-the-container-from-source) | Git checkout, Docker and the source-build override |
|
||||
| Linux server without Docker | [Native Linux](NATIVE_INSTALL.md) | Python 3.14, Node 24, private configuration and two systemd services |
|
||||
| Local development or foreground use without Docker | [Linux/macOS/Windows](LOCAL_DEVELOPMENT.md) | Native dependencies and two terminal processes; no service-manager installation |
|
||||
|
||||
## Platform and support boundaries
|
||||
|
||||
- The published container has been built and smoke-tested for **Linux/amd64**.
|
||||
Check the registry manifest before choosing another architecture. ARM64,
|
||||
Raspberry Pi and Apple Silicon native-image support are not advertised;
|
||||
amd64 emulation is not native ARM64 validation.
|
||||
- Docker Desktop on Windows/macOS runs Linux containers in a Linux environment;
|
||||
it is not a native Windows container or native macOS application. Enable Linux
|
||||
containers. WSL2 can also host the Linux instructions when its prerequisites
|
||||
are installed; systemd availability depends on that WSL installation.
|
||||
- The native Linux systemd files are deployment examples, not an unattended OS
|
||||
installer or a certification of every distribution. Install compatible Python,
|
||||
Node and native dependencies using their maintainers' instructions. Native
|
||||
foreground checks do not prove boot-time service operation on another OS.
|
||||
- Windows/macOS foreground instructions are for local evaluation/development.
|
||||
This repository does not ship Windows Service or launchd installers.
|
||||
- Run **one backend process/worker and one writable SQLite instance**. Do not
|
||||
share its database between replicas, combine old/new versions against the same
|
||||
data, or put SQLite on network storage. Kubernetes/Swarm/HA deployments are not
|
||||
supplied or validated by these single-instance examples.
|
||||
|
||||
## Before starting
|
||||
|
||||
Choose a stable browser URL, reserve the required ports, and decide where your
|
||||
persistent data and off-host backups will live. Storage use depends on request
|
||||
history and optional artwork caching; leave additional room for backup staging
|
||||
and rollback copies. Source builds also need dependency/build space and more
|
||||
memory than the running application. No universal RAM/disk minimum has been
|
||||
benchmarked.
|
||||
|
||||
For public use, configure DNS and HTTPS before creating the administrator. On a
|
||||
trusted LAN, HTTP can be used deliberately; do not forward its plain-HTTP port
|
||||
directly to the internet. Container examples publish **3000**; the browser uses
|
||||
`/api` on that same frontend address. The backend's **8000** port should not be
|
||||
exposed publicly. Native production examples bind both services to loopback.
|
||||
|
||||
An app address entered into Magent must be reachable from the Magent runtime.
|
||||
Container `localhost` is that container, not your Docker host. Native `localhost`
|
||||
is the native host. Docker Desktop provides `host.docker.internal`; do not assume
|
||||
that name exists in every Linux Engine deployment. Never mount the Docker socket
|
||||
into Magent to make service discovery work.
|
||||
|
||||
## HTTPS and reverse proxy
|
||||
|
||||
Magent needs its own origin, such as `https://magent.example.com`. These examples
|
||||
serve at `/`, not under a `/magent` subpath. Do not put a second login portal in
|
||||
front of the API without testing cookies and redirects.
|
||||
|
||||
If [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy) runs directly
|
||||
on the same host as the frontend, the site block is:
|
||||
|
||||
```caddyfile
|
||||
magent.example.com {
|
||||
reverse_proxy 127.0.0.1:3000
|
||||
}
|
||||
```
|
||||
|
||||
Point public DNS to your proxy's public address and make its certificate
|
||||
validation ports reachable as required by your Caddy deployment. Validate and
|
||||
reload your existing proxy configuration, preserving other sites. If the proxy
|
||||
is itself a container or runs elsewhere, `127.0.0.1` refers to that proxy: use a
|
||||
reachable Magent address/shared network instead. Do not blindly replace an
|
||||
existing proxy configuration with this single block.
|
||||
|
||||
For an existing [nginx](https://nginx.org/en/docs/http/ngx_http_proxy_module.html)
|
||||
HTTPS server with certificates already configured, use a `location /` that
|
||||
proxies to `http://127.0.0.1:3000`, preserves `Host`, sets
|
||||
`X-Forwarded-Proto $scheme` and `X-Forwarded-For $proxy_add_x_forwarded_for`,
|
||||
uses `proxy_read_timeout 180s`, disables proxy buffering for streaming responses,
|
||||
and permits `client_max_body_size 34m` for encrypted restore uploads. TLS key
|
||||
paths and certificate issuance are operator-owned; Magent does not create them.
|
||||
Do not add a second CSP that blocks Magent's nonce-authorized scripts.
|
||||
|
||||
## First administrator and apps
|
||||
|
||||
1. Wait for frontend and API health checks to pass, then open `/setup` at the
|
||||
exact address your users will use.
|
||||
2. Obtain the private setup token through the console for your installation
|
||||
method. Containers generate it automatically; native/manual installations
|
||||
generate and persist it in their private backend configuration. The
|
||||
**Get setup token** button is console help, not a public token-retrieval API.
|
||||
3. Confirm the URL and create a local administrator with a unique password of
|
||||
at least 12 characters. Never share the token in a ticket or screenshot.
|
||||
4. Configure only the integrations you need and use **Save & test**. Optional
|
||||
integrations can be skipped. Review preferences and finish setup.
|
||||
5. Create an encrypted backup, keep its passphrase separately and test recovery.
|
||||
|
||||
Container-managed installations save their URL and derive CORS/cookie behavior
|
||||
from it. **Native/manual installations must configure URL, CORS and cookie HTTPS
|
||||
settings explicitly**; changing a wizard field does not edit an environment
|
||||
file. If moving from HTTP to HTTPS, update both native environment files and
|
||||
restart the services as described in their guide.
|
||||
|
||||
## Operations and troubleshooting
|
||||
|
||||
Use [backup and recovery](installation-and-recovery.md) for exports/restores and
|
||||
your selected guide for restarts, upgrades and rollback. Keep the original
|
||||
database, private signing/encryption keys and deployment configuration. A new
|
||||
empty volume or regenerated keys is not an upgrade. Never repair a login problem
|
||||
by deleting the database or turning off origin protections.
|
||||
|
||||
| Symptom | Check |
|
||||
| --- | --- |
|
||||
| Setup token is rejected | Correct instance/token, no admin already created, no leading/trailing paste errors; manual env was actually loaded |
|
||||
| Login rejected or cross-origin error | Exact browser origin, manual CORS, application URL and HTTP/HTTPS cookie settings agree |
|
||||
| Page has huge logo/no styles or hangs loading | Browser Network/Console for CSS/JS/CSP failures; standalone static/public files copied; HTTP URL explicit where required |
|
||||
| `/api` returns 502 | API health, frontend's build-time backend address, container network or native loopback listener |
|
||||
| Database/branding/backup permission error | Correct unprivileged owner and persistent data path; native working directory matters for assets |
|
||||
| Login disappears after restart | Same volume/database and keys retained; correct cookie origin; not alternating between different instances |
|
||||
| Restore upload rejected | Archive limits, proxy's 34 MiB request allowance, sufficient private staging space |
|
||||
| Old UI after updating | Re-pull/recreate the container, or rebuild native standalone files; source changes alone do not replace runtime artifacts |
|
||||
|
||||
All supported environment settings are in [ENVIRONMENT.md](ENVIRONMENT.md).
|
||||
[PUBLIC_RELEASE.md](PUBLIC_RELEASE.md) covers advanced manual-key container
|
||||
deployments and release verification. Report problems with versions, architecture,
|
||||
installation method and sanitized errors—not credentials or database contents.
|
||||
|
||||
## Validation notes
|
||||
|
||||
Checked on 20 September 2026:
|
||||
|
||||
- The prebuilt and source-build Compose configurations passed Docker Compose
|
||||
validation. Documented shell examples and relative links were checked.
|
||||
- The native foreground path was smoke-tested on Windows with Python 3.14 and
|
||||
Node.js 24: first-admin setup, browser assets, login, origin checks, API proxy
|
||||
and persistence after a backend restart passed.
|
||||
- Linux systemd examples passed static directive validation. They were not
|
||||
started end-to-end on a Linux host in this check; install the required
|
||||
runtimes and verify their executable paths before enabling the services.
|
||||
- The macOS foreground instructions were reviewed but not runtime-tested.
|
||||
Reference in New Issue
Block a user