Skip to main content

Container Deployment Guide

This guide covers running MAPS Messaging via Docker Compose. For image build details, see the Dockerfile in the repository.

Quick Start (Docker Compose)​

version: "3.8"
services:
  maps-messaging:
    image: mapsmessaging/maps-messaging:4.0.1   # pin a release tag (avoid :latest in prod)
    container_name: maps-messaging
    restart: unless-stopped
    ports:
      - "1883:1883"  # MQTT
      - "5672:5672"  # AMQP
      - "8080:8080"  # HTTP API
    volumes:
      - ./config:/opt/maps/config
      - ./schemas:/opt/maps/schemas
      - ./data:/data
    environment:
      - CONSUL_HOST=consul
      - SCHEMA_VALIDATION=true
    healthcheck:
      # Consider checking body for OK|Warning if you want 'unhealthy' only on Error
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 5

Snapshot builds: use a snapshot tag, e.g. mapsmessaging/maps-messaging:4.1.0-SNAPSHOT.

Tip: You may also parameterize the tag via an environment file (e.g., {MAPS_VERSION} in a .env).

Image & Tags​

Recommended published tags:

  • Stable: 4.0.1
  • Snapshots: 4.1.0-SNAPSHOT (and similar)

Tip: Always pin a specific tag in production to ensure repeatable deploys.

Ports, Volumes, Environment​

  • Ports

    • 1883 – MQTT

    • 1884 – MQTT-SN (1.2)

    • 2442 – MQTT-SN (2.0)

    • 4222 – NATS

    • 5672 – AMQP

    • 5683 – CoAP

    • 8080 – REST API (health, admin endpoints)

    • 8778 – Jolokia (if enabled)

    • 9000 – All protocols enabled by the license

    Expose only the ports you actually need.

  • Volumes

    • /opt/maps/config – configuration files
    • /opt/maps/schemas – schema definitions
    • /data – persistent runtime data

  • Environment variables (examples)

    • CONSUL_HOST – hostname/IP of Consul (if used)
    • SCHEMA_VALIDATION – enable/disable schema validation (true/false)

See the server configuration docs for the full list of supported environment variables and config files.

Upgrades & Rollback​

Upgrade in place:

docker compose pull
docker compose up -d

Rollback quickly by switching the tag in your Compose file (or .env) to the previous known-good version, then:

docker compose up -d

Build From Source (Optional)​

Most users should use the published images. If you need to build locally:

docker build -t mapsmessaging/maps-messaging:dev -f Dockerfile .