ignition-stack 0.1.0__py3-none-any.whl

ignition_stack/profiles/standalone.py

@@ -0,0 +1,44 @@
+"""Standalone profile: one full Ignition gateway + optional SQL DB.
+
+This is the Phase-2 walking skeleton's shape, surfaced as a named profile
+so the wizard can offer it alongside the multi-gateway profiles. The only
+knobs are the database choice (defaults to Postgres) and the optional
+reverse-proxy scaffold.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ignition_stack.config import DatabaseConfig, GatewayConfig, ProjectConfig
+from ignition_stack.profiles.base import Profile, ProfileOptions, register
+
+
+@dataclass(frozen=True)
+class StandaloneProfile:
+    slug: str = "standalone"
+    summary: str = "One full Ignition 8.3 gateway + Postgres. The default starter stack."
+
+    def build(self, name: str, options: ProfileOptions) -> ProjectConfig:
+        gateway = GatewayConfig()
+        if options.edge_role in {"gateway", "standalone"}:
+            gateway = gateway.model_copy(update={"ignition_edition": "edge"})
+
+        return ProjectConfig(
+            name=name,
+            profile=self.slug,
+            gateways=[gateway],
+            database=_database(options),
+            services=list(options.services),
+            reverse_proxy=options.reverse_proxy,
+        )
+
+
+def _database(options: ProfileOptions) -> DatabaseConfig | None:
+    if options.database_kind is None:
+        return None
+    return DatabaseConfig(kind=options.database_kind)
+
+
+# Side-effect: registers this profile when the module is imported.
+profile: Profile = register(StandaloneProfile())

ignition_stack/services/__init__.py

@@ -0,0 +1,25 @@
+"""Service catalog: per-service manifests, loader, and dependency resolver.
+
+Phase 5 turns every supported service (databases, MQTT brokers, Keycloak,
+simulators, Kafka, n8n) into a self-contained template directory under
+``ignition_stack/templates/services/<name>/`` holding a ``manifest.yaml``
+(metadata + capability declarations), a ``compose.yaml.j2`` fragment, and a
+``seed/`` tree. This package reads those manifests and resolves the implicit
+dependencies between services (Keycloak needs a SQL database; MySQL needs its
+JDBC driver) into a fully-expanded :class:`ProjectConfig` before the compose
+engine renders anything.
+"""
+
+from ignition_stack.services.loader import load_all_services, load_service, service_dir
+from ignition_stack.services.manifest import PostSetupItem, ServiceManifest
+from ignition_stack.services.resolver import ResolveError, resolve
+
+__all__ = [
+    "PostSetupItem",
+    "ResolveError",
+    "ServiceManifest",
+    "load_all_services",
+    "load_service",
+    "resolve",
+    "service_dir",
+]

ignition_stack/services/loader.py

@@ -0,0 +1,69 @@
+"""Load service manifests from the bundled ``templates/services/`` catalog."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib import resources
+from importlib.resources.abc import Traversable
+
+import yaml
+from pydantic import ValidationError
+
+from ignition_stack.services.manifest import ServiceManifest
+
+_SERVICES_PACKAGE = "ignition_stack.templates"
+_SERVICES_SUBDIR = "services"
+_MANIFEST_NAME = "manifest.yaml"
+
+
+class ServiceLoadError(Exception):
+    """Raised when a service manifest is missing or fails schema validation."""
+
+
+def services_root() -> Traversable:
+    """The ``templates/services/`` directory inside the installed package."""
+    return resources.files(_SERVICES_PACKAGE) / _SERVICES_SUBDIR
+
+
+def service_dir(name: str) -> Traversable:
+    """The ``templates/services/<name>/`` directory for one service."""
+    return services_root() / name
+
+
+def load_service(name: str) -> ServiceManifest:
+    """Load and validate one service's manifest by catalog slug."""
+    manifest_file = service_dir(name) / _MANIFEST_NAME
+    if not manifest_file.is_file():
+        raise ServiceLoadError(f"no manifest for service '{name}' (looked for {manifest_file}).")
+    try:
+        raw = yaml.safe_load(manifest_file.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ServiceLoadError(f"service '{name}' manifest is not valid YAML: {exc}") from exc
+    try:
+        manifest = ServiceManifest.model_validate(raw)
+    except ValidationError as exc:
+        raise ServiceLoadError(f"service '{name}' manifest failed validation:\n{exc}") from exc
+    if manifest.name != name:
+        raise ServiceLoadError(
+            f"service '{name}' manifest declares name '{manifest.name}'; they must match."
+        )
+    return manifest
+
+
+@lru_cache(maxsize=1)
+def load_all_services() -> dict[str, ServiceManifest]:
+    """Load every service manifest, keyed by slug.
+
+    Cached because the catalog is read-only package data: a single process
+    never sees it change. Tests that need a fresh read can call
+    ``load_all_services.cache_clear()``.
+    """
+    catalog: dict[str, ServiceManifest] = {}
+    for entry in services_root().iterdir():
+        if not entry.is_dir():
+            continue
+        if not (entry / _MANIFEST_NAME).is_file():
+            continue
+        manifest = load_service(entry.name)
+        catalog[manifest.name] = manifest
+    return catalog

ignition_stack/services/manifest.py

@@ -0,0 +1,106 @@
+"""Pydantic schema for a service ``manifest.yaml``.
+
+Each catalog service ships one manifest describing what the compose engine and
+the dependency resolver need to know about it without reading its Jinja2
+fragment:
+
+- **identity** - the catalog slug (also the compose service key and the
+  ``templates/services/<name>/`` directory name) and the human kind.
+- **image** - the default ``image:tag`` plus the ``.env`` key that overrides it.
+- **capabilities** - ``provides`` / ``requires`` capability tags the resolver
+  uses to wire implicit dependencies (Keycloak ``requires: [sql-database]``).
+- **env** - the preset ``.env`` keys this service contributes, with default
+  values, so the ``.env`` writer is data-driven instead of hardcoding each
+  service's credentials.
+- **seeding** - whether the service ships a ``seed/gateway-resources/`` tree
+  that the writer overlays onto every gateway's file-config resources (per the
+  Phase-1 seedability matrix), and which connections it cannot pre-seed and
+  must defer to ``POST-SETUP.md`` (Phase 7).
+
+The fragment itself references ``${ENV_KEY}`` values directly, so the manifest
+never duplicates the compose body - it only carries the metadata the engine
+cannot infer from YAML text.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# A service either lives on the user-facing ``frontend`` network or the private
+# ``backend`` network when ``network_split`` is on. Databases, brokers, IDPs,
+# simulators, and streaming brokers are backend; the only frontend service is
+# n8n (it exposes a UI users hit directly). Gateways always join both.
+NetworkTier = Literal["frontend", "backend"]
+
+ServiceKind = Literal[
+    "database",
+    "mqtt-broker",
+    "idp",
+    "simulator",
+    "streaming",
+    "automation",
+]
+
+
+class PostSetupItem(BaseModel):
+    """A connection this service cannot fully pre-seed from files.
+
+    Phase 7's ``POST-SETUP.md`` generator turns each of these into a manual
+    step. The ``connection`` matches a row in the Phase-1 seedability matrix;
+    ``reason`` quotes why the file-seeding path stops short (usually a secret
+    or a handshake the matrix marked ``no`` / ``partial``).
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    connection: str = Field(min_length=1)
+    reason: str = Field(min_length=1)
+
+
+class ServiceManifest(BaseModel):
+    """Declarative metadata for one catalog service."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(
+        min_length=1,
+        pattern=r"^[a-z][a-z0-9-]*$",
+        description="Catalog slug; also the compose service key and the directory name.",
+    )
+    kind: ServiceKind
+    summary: str = Field(default="", description="One-line description for docs and headers.")
+    image: str = Field(min_length=1, description="Default image:tag (overridable via image_env).")
+    image_env: str = Field(
+        min_length=1,
+        pattern=r"^[A-Z][A-Z0-9_]*$",
+        description="The .env key the compose fragment reads for this service's image.",
+    )
+    network: NetworkTier = Field(
+        default="backend",
+        description="Which network the service joins when network_split is on.",
+    )
+    provides: list[str] = Field(
+        default_factory=list,
+        description="Capability tags this service satisfies (e.g. 'sql-database').",
+    )
+    requires: list[str] = Field(
+        default_factory=list,
+        description="Capability tags this service needs; the resolver auto-adds a provider.",
+    )
+    env: dict[str, str] = Field(
+        default_factory=dict,
+        description="Preset .env keys -> default values this service contributes.",
+    )
+    seeds_gateway_resources: bool = Field(
+        default=False,
+        description=(
+            "True when the service ships seed/gateway-resources/ that the writer "
+            "overlays onto every gateway's file-config resource tree."
+        ),
+    )
+    post_setup: list[PostSetupItem] = Field(
+        default_factory=list,
+        description="Connections this service defers to POST-SETUP.md (Phase 7).",
+    )

ignition_stack/services/resolver.py

@@ -0,0 +1,133 @@
+"""Dependency resolver: expand a user's service selections into a full config.
+
+This is a **pure transformation**: given the raw :class:`ProjectConfig` the
+user (or wizard, in Phase 6) built, it returns a new, fully-resolved
+``ProjectConfig`` with every implicit dependency made explicit. The compose
+engine then renders that resolved config verbatim and never re-resolves at
+render time, which keeps the resolution rules unit-testable in isolation.
+
+Two kinds of rule run here, per the hybrid-resolution decision in the design:
+
+1. **Declarative** - each service manifest declares ``requires:`` capability
+   tags. If nothing in the stack provides a required capability, the resolver
+   auto-adds the default provider (today only databases are auto-addable:
+   Keycloak ``requires: [sql-database]`` -> a Postgres database appears).
+
+2. **Imperative** - a small ruleset for couplings that capability tags don't
+   express cleanly:
+   - Keycloak gets its own logical ``keycloak`` database created on the SQL
+     server it lands on.
+   - A MySQL database attaches the ``mysql-jdbc`` driver to every gateway so
+     the connector ``.jar`` lands in ``user-lib/jdbc/``.
+"""
+
+from __future__ import annotations
+
+from ignition_stack.config.schema import DatabaseConfig, ProjectConfig
+from ignition_stack.services.loader import load_all_services
+from ignition_stack.services.manifest import ServiceManifest
+
+
+class ResolveError(Exception):
+    """Raised when a selection can't be satisfied (unknown service, DB conflict)."""
+
+
+# Capability tags each database kind satisfies.
+_DB_CAPABILITIES: dict[str, set[str]] = {
+    "postgres": {"sql-database", "postgres-compatible"},
+    "mysql": {"sql-database", "mysql-compatible"},
+    "mariadb": {"sql-database", "mysql-compatible"},
+    "mongo": {"document-store"},
+}
+
+# When a required database capability is provided by nothing, add this kind.
+_DEFAULT_DB_FOR_CAPABILITY: dict[str, str] = {
+    "sql-database": "postgres",
+    "postgres-compatible": "postgres",
+    "mysql-compatible": "mysql",
+    "document-store": "mongo",
+}
+
+# Database kinds whose driver is not built into Ignition and must be attached
+# to gateways as a catalog JDBC entry (slug -> the modules.yaml driver slug).
+_DB_JDBC_DRIVER: dict[str, str] = {"mysql": "mysql-jdbc"}
+
+# Database kinds that host a per-application logical database for Keycloak.
+_KEYCLOAK_SQL_KINDS = {"postgres", "mysql", "mariadb"}
+
+
+def resolve(config: ProjectConfig) -> ProjectConfig:
+    """Return a deep copy of ``config`` with implicit dependencies expanded."""
+    catalog = load_all_services()
+    resolved = config.model_copy(deep=True)
+
+    _validate_services(resolved, catalog)
+    _satisfy_required_capabilities(resolved, catalog)
+    _apply_keycloak_database(resolved)
+    _apply_jdbc_drivers(resolved)
+
+    return resolved
+
+
+def _validate_services(config: ProjectConfig, catalog: dict[str, ServiceManifest]) -> None:
+    for svc in config.services:
+        if svc not in catalog:
+            known = ", ".join(sorted(catalog))
+            raise ResolveError(f"unknown service '{svc}'; known services: {known}")
+        if catalog[svc].kind == "database":
+            raise ResolveError(
+                f"'{svc}' is a database; set it as the project's 'database', not in 'services'"
+            )
+
+
+def _satisfy_required_capabilities(
+    config: ProjectConfig, catalog: dict[str, ServiceManifest]
+) -> None:
+    required: set[str] = set()
+    for svc in config.services:
+        required.update(catalog[svc].requires)
+
+    for cap in sorted(required):
+        if _capability_satisfied(cap, config, catalog):
+            continue
+        db_kind = _DEFAULT_DB_FOR_CAPABILITY.get(cap)
+        if db_kind is None:
+            raise ResolveError(
+                f"required capability '{cap}' is provided by no selected service "
+                "and cannot be auto-added"
+            )
+        if config.database is not None:
+            raise ResolveError(
+                f"a '{config.database.kind}' database is selected, but capability "
+                f"'{cap}' needs a different database and only one database is "
+                "supported per stack; choose a compatible database"
+            )
+        config.database = DatabaseConfig(kind=db_kind)
+
+
+def _capability_satisfied(
+    cap: str, config: ProjectConfig, catalog: dict[str, ServiceManifest]
+) -> bool:
+    if config.database is not None and cap in _DB_CAPABILITIES.get(config.database.kind, set()):
+        return True
+    return any(cap in catalog[svc].provides for svc in config.services)
+
+
+def _apply_keycloak_database(config: ProjectConfig) -> None:
+    if "keycloak" not in config.services or config.database is None:
+        return
+    if config.database.kind not in _KEYCLOAK_SQL_KINDS:
+        return
+    if "keycloak" not in config.database.extra_databases:
+        config.database.extra_databases.append("keycloak")
+
+
+def _apply_jdbc_drivers(config: ProjectConfig) -> None:
+    if config.database is None:
+        return
+    driver = _DB_JDBC_DRIVER.get(config.database.kind)
+    if driver is None:
+        return
+    for gw in config.gateways:
+        if driver not in gw.modules:
+            gw.modules.append(driver)

ignition_stack/templates/post-setup/_default.md.j2

@@ -0,0 +1,12 @@
+## Finish the {{ connection.replace('-', ' ') }} connection
+
+{{ reason }}
+
+- **Open the gateway UI:** {{ gateway_url }}
+- **Navigate to:** Config -> Connections, then open the `{{ connection }}` entry.
+{%- if env_vars %}
+- **Copy from `.env`:**
+{%- for key, value in env_vars %}
+  - `{{ key }}` = `{{ value }}`
+{%- endfor %}
+{%- endif %}

ignition_stack/templates/post-setup/device-connection.md.j2

@@ -0,0 +1,11 @@
+## Set up the device connection ({{ service }})
+
+{{ reason }}
+
+- **Open the gateway UI:** {{ gateway_url }}
+- **Navigate to:** Config -> Device Connections -> Devices -> Create new Device, choose
+  the Modbus TCP driver, and point it at `{{ service }}` once the simulator is reachable.
+- **Copy from `.env`:**
+{%- for key, value in env_vars %}
+  - `{{ key }}` = `{{ value }}`
+{%- endfor %}

ignition_stack/templates/post-setup/gateway-network-link.md.j2

@@ -0,0 +1,18 @@
+## Approve the gateway-network link
+
+{{ reason }}
+
+This stack ships two gateways that aggregate over the **gateway-network**. The
+`gateway-network-link` row of the seedability matrix is partial, so approve the
+link by hand:
+{% for gw in gateways %}
+- **{{ gw.role }} gateway** (`{{ gw.name }}`): {{ gw.url }}
+{%- endfor %}
+
+1. Open the **frontend** gateway, go to Config -> Networking -> Gateway Network, and
+   add an outgoing connection to `${COMPOSE_PROJECT_NAME}-backend` on port 8060.
+2. Open the **backend** gateway and approve the incoming connection request.
+- **Copy from `.env`:**
+{%- for key, value in env_vars %}
+  - `{{ key }}` = `{{ value }}`
+{%- endfor %}

ignition_stack/templates/post-setup/identity-provider.md.j2

@@ -0,0 +1,13 @@
+## Finish the OIDC identity provider (Keycloak)
+
+{{ reason }}
+
+- **Open Keycloak:** http://localhost:{{ env_map['KEYCLOAK_HTTP_PORT'] }}
+  (admin console -> Clients -> `ignition-gateway` -> Credentials -> copy the client secret)
+- **Open the gateway UI:** {{ gateway_url }}
+- **Navigate to:** Config -> Security -> Identity Providers, then add/edit the OIDC IdP.
+- **Copy from `.env`:**
+{%- for key, value in env_vars %}
+  - `{{ key }}` = `{{ value }}`
+{%- endfor %}
+- Paste the client secret you copied from Keycloak into the gateway IdP's **Client Secret** field.

ignition_stack/templates/post-setup/kafka-connector.md.j2

@@ -0,0 +1,11 @@
+## Configure the Kafka connector
+
+{{ reason }}
+
+- **Open the gateway UI:** {{ gateway_url }}
+- **Navigate to:** Config -> Kafka -> Connectors -> Create new Kafka connector, and
+  point its bootstrap servers at `kafka:9092`.
+- **Copy from `.env`:**
+{%- for key, value in env_vars %}
+  - `{{ key }}` = `{{ value }}`
+{%- endfor %}

ignition_stack/templates/post-setup/mcp-module.md.j2

@@ -0,0 +1,11 @@
+## Drop in the Ignition MCP module
+
+{{ reason }}
+
+- **Request the module:** https://inductiveautomation.com/early-access (Ignition MCP,
+  Early-Access).
+- **Drop the file here:** `{{ dropin_dir }}/<filename>.modl`
+- Re-run `docker compose up -d`; the bootstrap copies any `.modl` in the drop-in dir
+  into the gateway's `user-lib/modules/` on startup.
+- **Open the gateway UI:** {{ gateway_url }}
+- **Navigate to:** Config -> Modules to confirm the MCP module loaded.

ignition_stack/templates/post-setup/mqtt-engine-connection.md.j2

@@ -0,0 +1,11 @@
+## Link the gateway to the MQTT broker ({{ service }})
+
+{{ reason }}
+
+- **Open the gateway UI:** {{ gateway_url }}
+- **Navigate to:** Config -> MQTT Engine -> Servers -> Settings (use MQTT Transmission
+  on an edge gateway instead), then add an MQTT server pointing at `{{ service }}`.
+- **Copy from `.env`:**
+{%- for key, value in env_vars %}
+  - `{{ key }}` = `{{ value }}`
+{%- endfor %}

ignition_stack/templates/post-setup/opc-ua-connection.md.j2

@@ -0,0 +1,11 @@
+## Confirm the OPC-UA connection ({{ service }})
+
+{{ reason }}
+
+- **Open the gateway UI:** {{ gateway_url }}
+- **Navigate to:** Config -> OPC Connections -> Servers, then open the seeded OPC-UA
+  connection and confirm its endpoint URL and security mode against the running simulator.
+- **Copy from `.env`:**
+{%- for key, value in env_vars %}
+  - `{{ key }}` = `{{ value }}`
+{%- endfor %}

ignition_stack/templates/post-setup/reverse-proxy.md.j2

@@ -0,0 +1,8 @@
+## Install the reverse proxy
+
+{{ reason }}
+
+- **Read the scaffolded README:** `{{ proxy_path }}/README.md`
+- Clone ia-eknorr/traefik-reverse-proxy into `{{ proxy_path }}/` and follow its routing
+  and TLS instructions to put it in front of the gateway.
+- **Open the gateway UI:** {{ gateway_url }} (today a plain host-port mapping).

ignition_stack/templates/services/chariot/compose.yaml.j2

@@ -0,0 +1,17 @@
+{{ name }}:
+  image: {{ image_ref }}
+  hostname: {{ name }}
+  container_name: {{ container_name_ref }}
+  environment:
+    TZ: ${TZ}
+    ACCEPT_EULA: "true"
+    ADMIN_PASSWORD: ${CHARIOT_ADMIN_PASSWORD}
+  ports:
+    - "${CHARIOT_HTTP_PORT}:8080"
+    - "${CHARIOT_MQTT_PORT}:1883"
+{%- if networks %}
+  networks:
+{%- for net in networks %}
+    - {{ net }}
+{%- endfor %}
+{%- endif %}

ignition_stack/templates/services/chariot/manifest.yaml

@@ -0,0 +1,22 @@
+# Chariot - the Cirrus Link MQTT broker, the primary pick for Sparkplug SCADA
+# demos. Web UI + MQTT, commissioned from env on first boot.
+name: chariot
+kind: mqtt-broker
+summary: Cirrus Link Chariot MQTT broker (Sparkplug-aware, web UI).
+image: cirruslink/chariot:3.0.0
+image_env: CHARIOT_IMAGE
+network: backend
+provides:
+  - mqtt-broker
+requires: []
+env:
+  CHARIOT_ADMIN_PASSWORD: password
+  CHARIOT_HTTP_PORT: "8090"
+  CHARIOT_MQTT_PORT: "1886"
+seeds_gateway_resources: false
+post_setup:
+  - connection: mqtt-engine-connection
+    reason: >-
+      Linking an Ignition gateway to the broker needs the Cirrus Link MQTT
+      Engine/Transmission module plus an MQTT server endpoint in the gateway,
+      configured once the stack is up.

ignition_stack/templates/services/chariot/seed/service/USAGE.md

@@ -0,0 +1,14 @@
+# Chariot MQTT Broker
+
+Sparkplug-aware MQTT broker from Cirrus Link, the primary broker for Ignition
+SCADA demos.
+
+- Web UI: http://localhost:${CHARIOT_HTTP_PORT} (user `admin`, password
+  `${CHARIOT_ADMIN_PASSWORD}`).
+- MQTT from another container: `tcp://chariot:1883`. From the host:
+  `tcp://localhost:${CHARIOT_MQTT_PORT}`.
+
+The EULA is auto-accepted (`ACCEPT_EULA=true`) so the broker commissions itself
+on first boot. To bridge an Ignition gateway, add the Cirrus Link MQTT
+Transmission/Engine modules and point them at `tcp://chariot:1883`
+(see POST-SETUP.md).

ignition_stack/templates/services/emqx/compose.yaml.j2

@@ -0,0 +1,16 @@
+{{ name }}:
+  image: {{ image_ref }}
+  hostname: {{ name }}
+  container_name: {{ container_name_ref }}
+  environment:
+    TZ: ${TZ}
+    EMQX_DASHBOARD__DEFAULT_PASSWORD: ${EMQX_DASHBOARD_PASSWORD}
+  ports:
+    - "${EMQX_MQTT_PORT}:1883"
+    - "${EMQX_DASHBOARD_PORT}:18083"
+{%- if networks %}
+  networks:
+{%- for net in networks %}
+    - {{ net }}
+{%- endfor %}
+{%- endif %}

ignition_stack/templates/services/emqx/manifest.yaml

@@ -0,0 +1,21 @@
+# EMQX - MQTT broker with a web dashboard.
+name: emqx
+kind: mqtt-broker
+summary: EMQX MQTT broker with management dashboard.
+image: emqx/emqx:6.2.0
+image_env: EMQX_IMAGE
+network: backend
+provides:
+  - mqtt-broker
+requires: []
+env:
+  EMQX_MQTT_PORT: "1884"
+  EMQX_DASHBOARD_PORT: "18083"
+  EMQX_DASHBOARD_PASSWORD: public
+seeds_gateway_resources: false
+post_setup:
+  - connection: mqtt-engine-connection
+    reason: >-
+      Linking an Ignition gateway to the broker needs the Cirrus Link MQTT
+      Engine/Transmission module plus an MQTT server endpoint in the gateway,
+      configured once the stack is up.

ignition_stack/templates/services/emqx/seed/service/USAGE.md

@@ -0,0 +1,11 @@
+# EMQX
+
+MQTT broker on `1883` (host port `${EMQX_MQTT_PORT}`) with a dashboard on
+`18083` (host port `${EMQX_DASHBOARD_PORT}`).
+
+- Dashboard: http://localhost:${EMQX_DASHBOARD_PORT} (user `admin`, password
+  `${EMQX_DASHBOARD_PASSWORD}`).
+- MQTT from another container: `tcp://emqx:1883`.
+
+To bridge an Ignition gateway, add the Cirrus Link MQTT Engine module and point
+its server endpoint at `tcp://emqx:1883` (see POST-SETUP.md).

ignition_stack/templates/services/hivemq/compose.yaml.j2

@@ -0,0 +1,12 @@
+{{ name }}:
+  image: {{ image_ref }}
+  hostname: {{ name }}
+  container_name: {{ container_name_ref }}
+  ports:
+    - "${HIVEMQ_MQTT_PORT}:1883"
+{%- if networks %}
+  networks:
+{%- for net in networks %}
+    - {{ net }}
+{%- endfor %}
+{%- endif %}

ignition_stack/templates/services/hivemq/manifest.yaml

@@ -0,0 +1,19 @@
+# HiveMQ CE - lightweight MQTT broker, anonymous access by default.
+name: hivemq
+kind: mqtt-broker
+summary: HiveMQ Community Edition MQTT broker.
+image: hivemq/hivemq-ce:2025.5
+image_env: HIVEMQ_IMAGE
+network: backend
+provides:
+  - mqtt-broker
+requires: []
+env:
+  HIVEMQ_MQTT_PORT: "1883"
+seeds_gateway_resources: false
+post_setup:
+  - connection: mqtt-engine-connection
+    reason: >-
+      Linking an Ignition gateway to the broker needs the Cirrus Link MQTT
+      Engine/Transmission module plus an MQTT server endpoint in the gateway,
+      configured once the stack is up.

ignition_stack/templates/services/hivemq/seed/service/USAGE.md

@@ -0,0 +1,16 @@
+# HiveMQ CE
+
+Anonymous MQTT broker listening on `1883` (host port `${HIVEMQ_MQTT_PORT}`).
+
+From another container on the stack, connect to `tcp://hivemq:1883`. From the
+host, use `tcp://localhost:${HIVEMQ_MQTT_PORT}`.
+
+Quick check with the Mosquitto CLI:
+
+```bash
+mosquitto_sub -h localhost -p ${HIVEMQ_MQTT_PORT} -t 'demo/#' &
+mosquitto_pub -h localhost -p ${HIVEMQ_MQTT_PORT} -t 'demo/hello' -m 'from ignition-stack'
+```
+
+To bridge an Ignition gateway to this broker, add the Cirrus Link MQTT Engine
+module and point its server endpoint at `tcp://hivemq:1883` (see POST-SETUP.md).