Deployment Modes

Deployment Modes

This page documents supported deployment patterns from project-code/.

When To Use This Page

Use this page when selecting or switching run modes (local, profile-based, cluster, swarm ingress).

1. Local Development (Default)

docker compose up -d --build

Characteristics:

• Single EMQX node (emqx-main).
• Local source broker (source-broker) for deterministic development.
• mqtt-radar and mqtt-simulator are profile-gated by default.

2. Optional Local Profiles

Standalone RADAR profile

docker compose --profile standalone-radar up -d mqtt-radar

MQTT simulator profile

docker compose --profile mqtt-sim up -d --build --force-recreate mqtt-simulator

Start full stack including simulator:

docker compose --profile mqtt-sim up -d --build

3. EMQX Two-Node Cluster Mode

docker compose -f docker-compose.yml -f docker-compose.cluster.yml up -d --build

Adds emqx-worker and cluster seed wiring for multi-node broker behavior testing.

4. Swarm Mode (Base)

docker stack deploy -c docker-compose.swarm.yml off-key

Use for replicated frontend/API and overlay-network operation.

5. Swarm Ingress Overlay (Tailscale + gost)

1. Copy ingress template:

cp .env.ingress.example .env.ingress.local

2. Fill required values (INGRESS_UPSTREAM_MQTT_HOST, auth settings, state directory).

3. Deploy overlay stack:

docker stack deploy \
  --env-file .env.ingress.local \
  -c docker-compose.swarm.yml \
  -c docker-compose.ingress.yml \
  off-key

4. Configure EMQX bridge target to mqtt-tailscale-bridge:1883 with upstream auth/TLS/topics.

Safe Mode Switching

When moving between local/cluster/ingress modes:

docker compose down -v
docker network rm off-key_app-network off-key_emqx-network || true

Then start target mode from a clean baseline.

Mode Selection Guidance

Goal	Recommended Mode
Day-to-day development	Local default
Test detection logic with synthetic data	Local + mqtt-sim profile
Test multi-node EMQX behavior	Local + cluster override
VPN ingress from external broker	Swarm + ingress overlay

Configuration Source Of Truth

Use Environment Variables for per-mode variable setup.

Related Pages

• Getting Started
• Architecture Overview
• Environment Variables
• Testing & Debugging