feat(release): publish minimal self-contained Magent source
This commit is contained in:
Magent release tooling
@@ -0,0 +1,175 @@
|
||||
# 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 still needs publishing to Docker Hub. These repository
|
||||
changes have not published an image or changed a live deployment. Until the
|
||||
release owner updates `latest` with this release, the template may pull an older
|
||||
image that lacks these features. `latest` is mutable, not an immutable release
|
||||
identifier; record the deployed digest and review release notes before updating.
|
||||
|
||||
## 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.
|
||||
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.
|
||||
Reference in New Issue
Block a user