Magent/docs/PORTAINER.md

# Install with Portainer

For a **fresh installation**, paste [compose.yml](../compose.yml) into a new
Portainer stack and deploy with **no environment variables**. The stack names
`image: rephl3xnz/magent:latest` directly. Portainer pulls that prebuilt Docker Hub image; Magent
creates its private keys, database and persistent storage, then guides you
through administrator and app setup. Users do not need a Dockerfile, source
checkout, Python installation, `.env` file or another database container.

**Release availability:** the image with zero-input managed bootstrap and
wizard-configured origins is published on Docker Hub. `latest` is mutable, not
an immutable release identifier; record the deployed digest and review release
notes before updating. If an existing stack still uses an older image, updating
the Compose text alone does not pull the new image: explicitly re-pull it when
redeploying, while retaining the same persistent volume.

## Requirements

- A Portainer-managed **Docker Standalone** environment running Linux containers.
  This template is for one Magent instance, not Docker Swarm or multiple replicas
  sharing SQLite.
- A compatible published image for your CPU architecture. Only `linux/amd64`
  has been validated; do not assume ARM64 support.
- A stable address you will actually use in your browser. Use HTTPS before
  exposing Magent publicly or inviting internet users.
- Existing media services, if you want to connect them. This stack installs
  Magent, not Jellyfin, Seerr or the Arr applications.

## Deploy and finish setup

1. In your Docker environment, open **Stacks**, choose **Add stack**, name it
   `magent`, and select **Web editor**. Paste the complete root `compose.yml`.
   Uploading that file is an alternative. See
   [Portainer's stack instructions](https://docs.portainer.io/user/docker/stacks/add).
2. Leave the stack's **Environment variables** section empty. Keep the
   runtime-security block unchanged. No signing keys, database path, API-docs
   flag, application URL or CORS value needs entering into the stack.
3. Choose **Deploy the stack** and wait for the Magent container to become
   healthy. The image's non-root user owns a fresh named volume automatically.
4. Open that container's **Console**, choose command `/bin/ash` and user
   **`magent`** (UID `1000`), connect, and run:

   ```sh
   python -m app.container_bootstrap setup-token
   ```

   This deliberately displays a private first-install token only in your
   administrative console, not the normal container logs. Keep the output
   private: anyone with that token and access to an unclaimed installation can
   create its first administrator. The command refuses to reveal it once an
   administrator exists.
   The setup page's **Get setup token** button also shows these instructions and
   offers **Copy command**. On browsers without clipboard access, select and
   copy the displayed command manually. This help dialog does not generate or
   reveal a token over the public web interface.
5. Open Magent at the browser address you intend to use, such as
   `http://192.168.1.50:3000` on a trusted LAN or `https://magent.example.com`
   through your configured HTTPS proxy. Use the **Docker host's reachable
   address**, not Portainer's address if Portainer runs elsewhere. The fresh
   installation opens `/setup`. Confirm the application URL shown there,
   enter the token and create your administrator with a unique password. The
   confirmed URL must match the browser origin, including any non-default port,
   with no path, trailing slash, credentials or query string. To choose another
   address, open setup at that address first. Token-authorized creation saves
   the URL and administrator together; arbitrary visitors cannot claim a trusted
   origin merely by loading a page. Then connect/test the apps you use, select
   preferences and finish. Optional apps can be skipped. There is no shared
   default administrator password.
6. Make an encrypted backup from **Settings → Advanced tools → Backup & restore**
   and save its passphrase separately. Test recovery before relying on the
   installation.

There is no need to manually generate keys or remove an environment setup token
in this mode. First-admin creation stops accepting the token after an account
has been created. Restarting or recreating the container retains the same
database and keys; it does not reopen first-admin signup.
Managed CORS and cookie security follow the saved URL automatically. SQLite is
fixed at `/app/data/magent.db`, and API documentation is disabled; neither is a
setup choice. All environment options, including advanced legacy overrides, are
listed in the [complete environment reference](ENVIRONMENT.md).

App connection URLs must be reachable **from Magent's container**. `localhost`
refers to Magent itself, not the Docker host or another application. Use LAN/DNS
addresses or explicitly attach applications to an appropriate shared Docker
network. Never mount the Docker socket into Magent.

## Ports, HTTPS and security defaults

The default publishes host port `3000` on all interfaces so a browser on the LAN
can reach a typical Portainer deployment. Restrict that port with your host and
network firewall. Do not port-forward this plain-HTTP endpoint to the internet.
Only port 3000 is published; browser API requests use `/api` on the same origin.

The default port mapping is the literal `3000:3000`; this template has no variable
substitutions. An operator needing another host port can deliberately edit only
the left-hand port, then use/confirm that address in setup. For a reverse proxy
running directly on the Docker host, `127.0.0.1:3000:3000` restricts the listener
to host loopback. A containerized proxy instead needs an explicitly shared Docker
network or reachable host interface; its own loopback is not the Docker host.

For public service, configure DNS and an HTTPS reverse proxy, set
the application URL to the external `https://` origin in setup/admin.
Managed installations derive matching CORS and Secure cookies from that saved
URL, while an explicitly confirmed private HTTP origin permits HTTP cookies.
They do not install a certificate or reverse proxy. See the
[reverse-proxy guide](PUBLIC_RELEASE.md#https-public-urls-and-reverse-proxies).
Keep the configured address consistent: visiting an IP when the configured
origin is a domain can make sign-in fail the origin check.

The following Docker runtime controls stay enabled in the Compose file:

- `read_only: true` protects the image filesystem; only the data volume and
  designated temporary areas are writable.
- `cap_drop: ["ALL"]` and `security_opt: ["no-new-privileges:true"]` restrict
  process privileges.
- `init: true` handles child-process reaping and signal forwarding.
- `tmpfs` supplies restricted temporary writable areas for process state and
  frontend cache without making the image writable.

**Leave this security block unchanged.** These are Docker engine settings, not
application environment variables; deleting them does not make them implicit
image defaults. No privileged container or Docker socket access is required.

Advanced/manual environment installs remain supported separately; see
[ENVIRONMENT.md](ENVIRONMENT.md). Adding an unreferenced variable to Portainer's
variable list alone does not inject it into this no-variable template. Do not
add manual secrets or attempt to override fixed managed defaults in a working
managed installation.

HTTP is intended for trusted-LAN setup/testing, not a fully secure deployment.
Some browser features (such as clipboard access and report/newsletter operations
using secure-context APIs) require HTTPS. Configure HTTPS for ongoing use.

## Persistence, backups and upgrades

Keep the stack name stable. Docker creates a project-scoped `magent-data` named
volume mounted at `/app/data`. It holds the database, cached artwork, branding
and `/app/data/bootstrap-secrets.json`, which contains the generated signing key,
settings-encryption key and setup token. Its restrictive permissions do not
protect it from the Docker host administrator: restrict Portainer/host access
and use encrypted host storage. Treat the complete volume as sensitive.

Never delete that file to fix a startup or login problem. Without the original
encryption key, a raw database copy's encrypted credentials cannot be recovered.
Keep a secure, consistent offline backup of the **whole volume** by stopping
only Magent while taking the copy. Preserve the generated secrets with that
copy. A portable `.magent-backup` export is different: it excludes deployment
keys and re-encrypts settings for the destination's keys during restore. See
[backup and recovery](installation-and-recovery.md).
Managed application-backup restore also retains the destination's confirmed
application URL, not the backup source's URL. Its origin/cookie policy therefore
continues to match the destination site. An offline full-volume restore is a
different procedure and must preserve that volume's original keys.

Before updating, save the current image tag/digest, stack definition and backup.
Update the existing stack with a fresh pull of `rephl3xnz/magent:latest`, retaining
its name and volume. A plain container restart does not pull an updated image.
For a controlled release or rollback, edit only the `image:` line to a compatible
published immutable tag or digest; this is optional, not an installation input.
Verify health, login,
app connections and invites afterwards. Rollback may require the matching data
backup if a migration is not backward compatible.

Do not remove volumes when deleting/recreating a stack unless you intend to
erase the installation. Changing the stack name or mounting an empty volume
does not migrate your data.

## Existing installations

This is a **fresh-install template**, not an automatic migration from manual
secrets. Existing installations must retain their own data mount, database path,
`JWT_SECRET`, `SETTINGS_ENCRYPTION_KEY` and deployment settings. Continue using
your saved stack or [docker-compose.hub.yml](../docker-compose.hub.yml). Do not
switch an existing bind mount to a fresh named volume or enable managed secrets
to replace established keys. Follow an explicitly reviewed migration if you
choose to change secret management later.

The project retains its Dockerfile for maintainers to build release images.
End users deploying this stack do not download or run it.