Install with Portainer

For a fresh installation, paste 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

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.
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.
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.
Open that container's Console, choose command /bin/ash and user magent (UID 1000), connect, and run:
```
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.
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.
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.

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

10 KiB Raw Permalink Blame History