Self-hosted team communication you control.
MatrixEasyMode is open source communication software for teams that want privacy, operator control, and a deployment story they can actually reason about.
This repository contains the operator-facing deployment pack for running MatrixEasyMode with Docker Compose. It is written for Linux-first operators who are comfortable with domains, DNS, reverse proxies, certificates, container networking, and reading logs when something goes wrong.
MatrixEasyMode provides a practical operator UI for creating, provisioning, and opening private chat instances.
Official documentation
The canonical documentation lives on the official website:
- Get Started: https://matrixeasymode.com/get-started
- Docs index: https://matrixeasymode.com/docs
- Project website: https://matrixeasymode.com
This is the shortest correct path for most operators.
git clone https://github.com/matrix-easy-mode/mem-deploy
cd mem-deployIf you already have a checkout:
git pull --ff-onlychmod +x install.sh stack.sh tools.sh./install.shThe installer will:
- create
.env - generate required secrets
- prompt for runtime configuration
- prompt for image source (
registryorlocal) - validate the Docker Compose configuration
- optionally start infrastructure for you
./stack.sh up infraThis starts:
postgresnpm
Before starting the app layer, you must:
- open Nginx Proxy Manager
- log in with the credentials you configured during install
- create or confirm the wildcard certificate referenced by
INGRESS_CERTIFICATE_NAME - confirm your public DNS is pointing at the correct host
NPM admin UI:
http://<your-server>:81
./stack.sh up appThis starts:
apiweb
./stack.sh status
./stack.sh logs appTypical public URLs:
https://admin.your-domain.comhttps://api.your-domain.com
For the full operator install guide, use:
You should already be comfortable with:
- Linux shell access
- Docker Engine and Docker Compose
- public hostnames and DNS
- HTTPS and certificate management
- reverse proxies, especially Nginx Proxy Manager
- reading logs and troubleshooting service startup issues
You should also already have:
- a Linux host
- Docker Engine installed
- Docker Compose plugin installed
- a domain you control
- DNS records you can manage
- a plan for HTTPS certificates in Nginx Proxy Manager
MatrixEasyMode is not currently positioned as a beginner or one-click product. The current deployment model is intentionally operator-first.
This repository includes:
docker-compose.ymlfor the main MatrixEasyMode stackdocker-compose.local.ymlfor local developer image buildsdocker-compose.pgadmin.ymlfor optional pgAdmin accessinstall.shfor guided environment setup and staged startup preparationstack.shfor starting, stopping, restarting, building, updating, and viewing logstools.shfor optional operator tooling such as pgAdmin and Portainer.env.exampleas a reference template
This repository does not contain the MatrixEasyMode application source code itself. It is the deployment pack for operators.
The application source code is published separately in the mem-api and mem-web repositories.
This repository is the operator-facing deployment pack.
The open-source MatrixEasyMode application source code lives in separate repositories:
Use those repositories if you want to:
- review the application code
- build locally for development
- contribute changes
- understand API or frontend implementation details
If you are deploying MatrixEasyMode as an operator, stay in this repository and use the official docs:
The standard stack includes:
- PostgreSQL
- Nginx Proxy Manager
- MatrixEasyMode API
- MatrixEasyMode web frontend
MatrixEasyMode uses a staged startup model.
Infrastructure services:
postgresnpm
Application services:
apiweb
This separation is intentional. The MatrixEasyMode API bootstraps platform ingress routes into Nginx Proxy Manager, so NPM must already be running and the wildcard certificate must already exist before the application layer is started.
MatrixEasyMode supports two application image modes.
Use published images from a registry.
This is the normal path for operators evaluating or running MatrixEasyMode from release images.
Relevant settings include:
MEM_IMAGE_SOURCE=registry
MEM_REGISTRY
MEM_VERSION
Use locally built application images.
This is intended for contributors and internal developers who want to build and run MatrixEasyMode locally.
Relevant settings include:
MEM_IMAGE_SOURCE=local
MEM_API_IMAGE
MEM_WEB_IMAGE
When local mode is enabled, stack.sh automatically includes docker-compose.local.yml.
Typical local-mode flow:
./install.sh
./stack.sh build app
./stack.sh up infra
./stack.sh up app./stack.sh up infra./stack.sh up app./stack.sh up all./stack.sh status./stack.sh logs app./stack.sh logs infra./stack.sh logs api
./stack.sh logs web
./stack.sh logs postgres
./stack.sh logs npm./stack.sh build app./stack.sh restart app./stack.sh down app./stack.sh down infra./stack.sh down allThe website is the canonical documentation source.
- Get Started: https://matrixeasymode.com/get-started
- Docs index: https://matrixeasymode.com/docs
- Installation Guide
- Advanced Install
- Configuration
- Operations Guide
- Troubleshooting
- Upgrading
- Network Behavior
- Architecture
- Release notes
- Tools
- Optional pgAdmin
- Optional Portainer
If a long-form operational document exists both here and on the website, prefer the website version.
MatrixEasyMode also includes optional operator helpers through tools.sh.
./tools.sh pgadmin start
./tools.sh pgadmin stop
./tools.sh pgadmin status
./tools.sh pgadmin logs./tools.sh portainer start
./tools.sh portainer stop
./tools.sh portainer status
./tools.sh portainer logsThese tools are optional conveniences and are not part of the core MatrixEasyMode runtime.
If something looks wrong, start here:
./stack.sh status
./stack.sh logs infra
./stack.sh logs app
cat .envCommon causes of trouble are:
- the app layer was started before Nginx Proxy Manager was ready
- the wildcard certificate does not exist in NPM
.envvalues do not match the intended deployment- public URLs or DNS are wrong
- local-mode images were not built or build contexts are wrong
For the full troubleshooting guide, use the official docs:
- Security policy:
SECURITY.md - Change history:
CHANGELOG.md - Release notes:
releases/
For the latest project overview and official docs, see:
MatrixEasyMode is intentionally documented and packaged as operator software in this phase.
That means the workflow is explicit:
- infrastructure first
- application second
- environment-driven configuration
- certificate-aware ingress
- observable runtime behavior
- operator-controlled deployment
If that is the kind of self-hosted system you want, start here: