Magent/docs/INSTALLATION.md

# 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.