Configuration
Runtime configuration reference for MatrixEasyMode deployments.
The normal workflow is still script-first:
./install.shThat script generates .env for you. This guide explains what those values mean so you can review, understand, and adjust them when needed.
This document explains the runtime variables used by a MatrixEasyMode deployment.
The primary workflow in this repository is script-first:
./install.shThat script generates .env for you. In normal use, you should let the installer create the file, then review it if needed.
Configuration model
MatrixEasyMode currently uses a staged deployment model:
- infrastructure first
- PostgreSQL
- Nginx Proxy Manager
- application second
- MatrixEasyMode API
- MatrixEasyMode web frontend
The generated .env file provides the values consumed by:
docker-compose.ymlinstall.shstack.sh
For the broader install flow, see:
Environment file
MatrixEasyMode uses .env in the repository root.
Treat this file as sensitive. It contains secrets and should not be committed.
Recommended:
chmod 600 .envContainer images
MEM_REGISTRY
Container registry hosting the MatrixEasyMode images.
Example:
MEM_REGISTRY=ghcr.io/matrix-easy-modeMEM_VERSION
The image tag to deploy.
Examples:
MEM_VERSION=latest
MEM_VERSION=0.1.0Pinned versions are preferred for predictable deployments.
PostgreSQL settings
These values configure the bundled PostgreSQL container and the API connection string.
POSTGRES_USER
Database username for the bundled PostgreSQL container.
Example:
POSTGRES_USER=postgresPOSTGRES_PASSWORD
Database password used by PostgreSQL and the MatrixEasyMode API.
The installer lets you either:
- enter a password yourself, or
- press Enter and let it generate one
If you enter your own password, it must be at least 7 characters.
POSTGRES_DB
Database name created for MatrixEasyMode.
Example:
POSTGRES_DB=memJWT settings
These values are used by the API when issuing and validating tokens.
JWT_ISSUER
Issuer value used by the API when issuing tokens.
Example:
JWT_ISSUER=mem-apiJWT_AUDIENCE
Audience value expected by clients and the API.
Example:
JWT_AUDIENCE=mem-clientJWT_SIGNING_KEY
Long random key used to sign JWTs.
This should be treated as a secret.
Public application settings
These values define the public web-facing identity of the deployment.
NEXT_PUBLIC_APP_NAME
Friendly app name displayed in the frontend UI.
Example:
NEXT_PUBLIC_APP_NAME=MatrixEasyModeNEXT_PUBLIC_APP_DESCRIPTION
Short frontend description.
Example:
NEXT_PUBLIC_APP_DESCRIPTION=Self-hosted Matrix made easierNEXT_PUBLIC_SERVER_URL
Public browser URL for the frontend.
Example:
NEXT_PUBLIC_SERVER_URL=https://admin.your-domain.comIn most deployments, this should align with NEXTAUTH_URL.
NextAuth and web runtime settings
These values are used by the frontend and by internal web-to-API communication.
NEXTAUTH_URL
Public URL of the web application.
Example:
NEXTAUTH_URL=https://admin.your-domain.comThis is also used by the API as the public base URL for the platform web route.
NEXTAUTH_URL_INTERNAL
Internal callback URL used by the web container.
Default:
NEXTAUTH_URL_INTERNAL=http://web:3000This should normally remain on the Docker service name unless you have a specific reason to change it.
API_URL
Internal API URL used by the web container over the Docker network.
Default:
API_URL=http://api:7000This should normally remain on the Docker service name unless you have a specific reason to change it.
NEXT_PUBLIC_API_URL
Public API URL used by the browser.
Example:
NEXT_PUBLIC_API_URL=https://api.your-domain.comThis is also used by the API when bootstrapping the public API ingress route in Nginx Proxy Manager.
NEXTAUTH_SECRET
Secret used by NextAuth to sign and validate auth state.
This should be long, random, and treated as sensitive.
AUTH_TRUST_HOST
Whether the frontend should trust incoming host headers from the reverse proxy.
Typical value:
AUTH_TRUST_HOST=trueNginx Proxy Manager integration
MatrixEasyMode currently integrates with Nginx Proxy Manager for public ingress and HTTPS routing.
These values are used by the API to authenticate against and publish routes into the NPM API.
NPM_IDENTITY
Identity used by the API integration.
This must be an email address accepted by your NPM instance.
Example:
NPM_IDENTITY=admin@your-domain.comDo not use placeholder example domains.
NPM_SECRET
Secret or password used by the API integration.
This should match the NPM account you log into.
NPM_BASEURL
Base URL for the NPM API as seen from inside Docker.
Default bundled value:
NPM_BASEURL=http://npm:81/apiIn the bundled deployment, this points to the npm service on the shared Docker network.
Ingress and host naming
These values control certificate selection and host naming behavior.
INGRESS_CERTIFICATE_NAME
Certificate name already available in NPM and used for managed host creation.
Example:
INGRESS_CERTIFICATE_NAME=*.your-domain.comThe certificate must already exist in NPM before you start the MatrixEasyMode application layer.
HOSTNAMING_PUBLIC_HOST_SUFFIX
Public hostname suffix used when MatrixEasyMode generates public service hosts.
Example:
HOSTNAMING_PUBLIC_HOST_SUFFIX=your-domain.comHOSTNAMING_INTERNAL_HOST_SUFFIX
Internal hostname suffix used when MatrixEasyMode generates internal service hosts.
Example:
HOSTNAMING_INTERNAL_HOST_SUFFIX=your-domain.comIn many setups, these will match.
Matrix bootstrap settings
These values are used for Matrix bootstrap and provisioning flows.
MATRIXBOOTSTRAP_SHAREDSECRET
Shared secret used during Matrix bootstrap operations.
Treat this as sensitive.
MATRIXBOOTSTRAP_AUTOCREATEADMIN
Whether MatrixEasyMode should auto-create the bootstrap admin.
Typical value:
MATRIXBOOTSTRAP_AUTOCREATEADMIN=trueMATRIXBOOTSTRAP_ADMINUSERNAME
Bootstrap admin username.
Example:
MATRIXBOOTSTRAP_ADMINUSERNAME=svcadminMATRIXBOOTSTRAP_ADMINPASSWORD
Bootstrap admin password.
Treat this as sensitive.
Element Web setting
ELEMENTWEB_IMAGE
Container image used when provisioning Element instances.
Example:
ELEMENTWEB_IMAGE=vectorim/element-web:latestPlatform ingress bootstrap settings
These values control the platform route bootstrap process that creates or reconciles the main web and API routes inside NPM.
PLATFORMINGRESS_ENABLED
Whether platform ingress bootstrap is enabled.
Typical value:
PLATFORMINGRESS_ENABLED=truePLATFORMINGRESS_RETRYDELAYSECONDS
Retry delay in seconds while NPM or certificate prerequisites are not ready.
Typical value:
PLATFORMINGRESS_RETRYDELAYSECONDS=15PLATFORMINGRESS_RECONCILEONEVERYSTARTUP
Whether the platform ingress bootstrap should re-check and reconcile the web/API routes on every startup.
Typical value:
PLATFORMINGRESS_RECONCILEONEVERYSTARTUP=trueIf false, the system may skip work when a previously completed bootstrap state already matches the desired configuration.
How values are used together
For a typical deployment, the main route-related variables line up like this:
NEXTAUTH_URL=https://admin.your-domain.com
NEXTAUTH_URL_INTERNAL=http://web:3000
NEXT_PUBLIC_API_URL=https://api.your-domain.com
API_URL=http://api:7000
INGRESS_CERTIFICATE_NAME=*.your-domain.comThat means MatrixEasyMode will attempt to ensure routes equivalent to:
https://admin.your-domain.com->web:3000https://api.your-domain.com->api:7000
using the wildcard certificate already present in NPM.
Guidance
Use real public hostnames
Do not leave public URL values on localhost for a real deployment.
Use real hostnames such as:
admin.your-domain.comapi.your-domain.com
Protect .env
Recommended:
chmod 600 .envPrefer pinned versions
For predictable deployments, pin MEM_VERSION instead of relying on latest.
Review NPM integration carefully
Make sure:
NPM_BASEURLis reachable from the API container- the supplied NPM identity is valid
- the certificate name exists in NPM
- DNS and public hosts match the values you configured
Do not start the app layer too early
The app layer should be started only after:
- infrastructure is running
- you can log into NPM
- the wildcard certificate already exists in NPM
Typical sequence:
./install.sh
./stack.sh up infra
# log into NPM, create wildcard cert
./stack.sh up appUpdate the app layer deliberately
To pull and recreate the application containers:
./stack.sh update appThis is intentionally limited to the app layer. Infrastructure upgrades such as PostgreSQL and Nginx Proxy Manager should be handled manually and carefully.