Advanced Install

The standard MatrixEasyMode install path should be preferred unless you have a specific reason to deviate from it.

This guide covers situations where you need more direct control over image selection, local source layout, helper-script bypass, or the deployment shape.

When to use this guide

Use this page when one or more of these are true:

• you want to run MatrixEasyMode without relying on the helper scripts
• you need to use raw Docker Compose commands directly
• you are running local application images rather than published registry images
• your local source repositories do not match the default expected layout
• you want to inspect or control the staged startup flow more explicitly
• you need to adapt MatrixEasyMode to a non-default workflow

If you only want the normal install path, use:

• Get Started
• Installation Guide

What stays the same even in advanced mode

Advanced install does not remove the core deployment requirements.

These still apply:

• Nginx Proxy Manager must already be running before the app layer starts
• the wildcard certificate must already exist in NPM
• your public hostnames and DNS must already be correct
• the staged startup order still matters
• MatrixEasyMode still expects a self-hosted environment you control

The advanced path gives you more control, but it does not change the dependency model.

Standard path vs advanced path

Standard path

Use this when you want the recommended workflow:

./install.sh
./stack.sh up infra
./stack.sh up app

Advanced path

Use this when you want more control over the runtime flow:

• direct Docker Compose usage
• explicit image selection
• explicit build steps
• local source path adjustments
• deeper environment inspection before starting services

Environment model

Even when you use the advanced path, .env remains the central runtime configuration file.

The most important advanced-install values typically include:

• MEM_IMAGE_SOURCE
• MEM_REGISTRY
• MEM_VERSION
• MEM_API_IMAGE
• MEM_WEB_IMAGE
• NEXTAUTH_URL
• NEXT_PUBLIC_API_URL
• NPM_BASEURL
• NPM_IDENTITY
• NPM_SECRET
• INGRESS_CERTIFICATE_NAME

Review the generated .env before starting services if you are deviating from the standard path.

For the broader environment model, see the Installation Guide.

Registry mode in more detail

Registry mode is the normal path when you want published images.

Typical relevant settings are:

MEM_IMAGE_SOURCE=registry
MEM_REGISTRY=<your registry>
MEM_VERSION=<your version>

In this mode:

• you do not build the API and web images locally
• image tags come from the configured registry and version
• docker-compose.local.yml is not part of the normal runtime path

Registry mode with raw Docker Compose

Start infrastructure first:

docker compose up -d

Then start the application layer:

docker compose --profile app up -d api web

Check status:

docker compose --profile app ps

Stop everything:

docker compose --profile app down --remove-orphans

This path is useful when you want to bypass stack.sh but still use the standard published-image model.

Local mode in more detail

Local mode is for contributors or users who want to build the application images themselves.

Typical relevant settings are:

MEM_IMAGE_SOURCE=local
MEM_API_IMAGE=mem-api:local
MEM_WEB_IMAGE=mem-web:local

In this mode:

• application images must be built locally
• docker-compose.local.yml is included in the runtime flow
• your local source directories must match the build contexts expected by the compose override

Build local images

./stack.sh build app

Or use Docker Compose directly:

docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app build api web

Start infrastructure in local mode

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d postgres npm

Start the app layer in local mode

docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app up -d api web

Check local-mode status

docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app ps

Stop everything in local mode

docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app down --remove-orphans

Local source layout expectations

Local mode assumes the required MatrixEasyMode application source repositories exist locally and that the paths referenced by docker-compose.local.yml are valid.

If your local repository layout differs from the default expected layout, review and adjust the compose override before building.

Typical advanced checks include:

• confirming the API build context points to the correct local repository
• confirming the web build context points to the correct local repository
• confirming your image tags in .env match the images you actually built
• confirming the local compose override is included in every relevant build and run command

If these do not line up, local mode will appear broken even though the runtime model itself is fine.

Running without helper scripts

The helper scripts are still the preferred path, but you can work without them when you need direct Compose control.

In that case, you are responsible for:

• selecting the correct compose files
• following the staged startup order
• ensuring environment variables are correct
• ensuring local-mode image builds happen before app startup
• reading raw Docker Compose status and logs directly

Raw status checks

Registry mode:

docker compose --profile app ps

Local mode:

docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app ps

Raw log inspection

Registry mode:

docker compose --profile app logs -f api web
docker compose logs -f postgres npm

Local mode:

docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app logs -f api web
docker compose -f docker-compose.yml -f docker-compose.local.yml logs -f postgres npm

Advanced startup order

MatrixEasyMode should still be brought up in this order:

1. confirm .env
2. start infrastructure
3. log into NPM
4. create or confirm the wildcard certificate
5. build local images if using local mode
6. start the application layer
7. verify routes, logs, and public endpoints

That order is not optional. The advanced path gives you more direct control, but it does not change the dependency model.

Nginx Proxy Manager assumptions

Do not start the app layer before Nginx Proxy Manager is ready.

Before starting the app layer, confirm:

• NPM is already reachable
• the NPM credentials in .env are valid
• the wildcard certificate is already present
• INGRESS_CERTIFICATE_NAME matches the certificate in NPM
• your public DNS already points where you expect

If any of those are wrong, ingress bootstrap can fail in ways that look like app problems when the real issue is ingress state.

Non-default adjustments

You may need to adapt MatrixEasyMode to a slightly different local environment.

Examples include:

• different local repository layout for source builds
• custom image tags
• custom registry naming
• explicit review of bind ports
• different local host preparation before first start
• stricter manual review of generated .env

These are valid reasons to use the advanced path, but each one should be treated as an intentional change rather than a surprise.

Troubleshooting advanced installs

If you are running the advanced path and something looks wrong, check these first.

1. Confirm image mode is what you think it is

Review:

cat .env

Pay particular attention to:

• MEM_IMAGE_SOURCE
• MEM_API_IMAGE
• MEM_WEB_IMAGE
• MEM_REGISTRY
• MEM_VERSION

2. Confirm the compose files match the mode

Registry mode should use the main compose path.

Local mode must include:

docker-compose.local.yml

3. Confirm local builds actually completed

For local mode:

./stack.sh build app

or:

docker compose -f docker-compose.yml -f docker-compose.local.yml --profile app build api web

4. Confirm NPM state before app start

Make sure:

• NPM is running
• credentials are valid
• certificate exists
• the certificate name matches .env

5. Confirm public URLs and DNS

Review:

• NEXTAUTH_URL
• NEXT_PUBLIC_API_URL

and verify that they match your intended public hostnames.

When to return to the standard path

If you do not specifically need the advanced path, return to the standard workflow.

Use the standard path when:

• you are evaluating MatrixEasyMode for the first time
• you want the least surprising deployment path
• you are not using local source builds
• you do not need raw Compose control
• you want the recommended setup flow

Start here when in doubt:

• Get Started
• Installation Guide

Related documentation

• Get Started
• Installation Guide
• Network Behavior
• Architecture