ignition-stack 0.1.0__py3-none-any.whl

ignition_stack/templates/services/rabbitmq/manifest.yaml

@@ -0,0 +1,23 @@
+# RabbitMQ - message broker; the bundled enabled_plugins turns on the MQTT
+# plugin so it can act as an MQTT broker alongside AMQP.
+name: rabbitmq
+kind: mqtt-broker
+summary: RabbitMQ broker with the MQTT plugin and management UI enabled.
+image: rabbitmq:4.3.1-management
+image_env: RABBITMQ_IMAGE
+network: backend
+provides:
+  - mqtt-broker
+requires: []
+env:
+  RABBITMQ_USER: ignition
+  RABBITMQ_PASSWORD: ignition
+  RABBITMQ_MQTT_PORT: "1885"
+  RABBITMQ_MGMT_PORT: "15672"
+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/rabbitmq/seed/service/enabled_plugins

@@ -0,0 +1 @@
+[rabbitmq_management,rabbitmq_mqtt].

ignition_stack/templates/standalone-postgres/docker-compose.yaml

@@ -0,0 +1,62 @@
+---
+# Generated by ignition-stack. Walking skeleton: one Ignition 8.3 gateway,
+# one Postgres, env-driven commissioning so first boot needs no UI.
+x-ignition-common: &ignition-common
+  image: &ignition-image ${IGNITION_IMAGE}
+
+x-ignition-environment: &ignition-environment
+  ACCEPT_IGNITION_EULA: "Y"
+  GATEWAY_ADMIN_USERNAME: ${ADMIN_USERNAME}
+  GATEWAY_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
+  IGNITION_EDITION: standard
+  TZ: ${TZ}
+
+services:
+  bootstrap:
+    image: *ignition-image
+    user: root
+    entrypoint: ["/bin/bash", "/docker-bootstrap.sh"]
+    environment:
+      GATEWAY_NAME: ${GATEWAY_NAME}
+    volumes:
+      - ignition-data:/data
+      - ./scripts/docker-bootstrap.sh:/docker-bootstrap.sh:ro
+      - ./services/ignition:/template-source:ro
+
+  gateway:
+    <<: [*ignition-common]
+    container_name: ${GATEWAY_NAME}
+    hostname: ${GATEWAY_NAME}
+    depends_on:
+      db:
+        condition: service_healthy
+      bootstrap:
+        condition: service_completed_successfully
+    ports:
+      - "${GATEWAY_HTTP_PORT}:8088"
+    volumes:
+      - ignition-data:/usr/local/bin/ignition/data
+    environment:
+      <<: *ignition-environment
+    command: >
+      -n ${GATEWAY_NAME}
+      -m 2048
+      --
+      -Dignition.config.mode=dev
+
+  db:
+    image: ${POSTGRES_IMAGE}
+    hostname: db
+    container_name: db-${GATEWAY_NAME}
+    environment:
+      TZ: ${TZ}
+      POSTGRES_USER: ${DB_USER}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    healthcheck:
+      test: ["CMD", "pg_isready", "-h", "localhost", "-U", "${DB_USER}"]
+      interval: 5s
+      timeout: 10s
+      retries: 10
+
+volumes:
+  ignition-data:

ignition_stack/templates/standalone-postgres/scripts/docker-bootstrap.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# Vendored from ignition-stack Phase 1 (scripts/seeding-poc/baseline/bootstrap.sh).
+#
+# This script runs once per gateway data volume. It:
+#   1. Copies the base /usr/local/bin/ignition/data into the persistent
+#      named volume so the gateway can write its .resources/ caches.
+#   2. Layers the project's resources and projects on top from a read-only
+#      /template-source mount. We copy (not :ro bind-mount) because the
+#      gateway needs to write .resources/ cache dirs inside those trees
+#      and an :ro bind blocks that.
+#   3. chown -R 2003:2003 /data so the gateway user owns everything. Without
+#      this, cp from a host bind-mount lands files owned by root or the
+#      host UID and the gateway faults with AccessDeniedException at start.
+#   4. Writes a deterministic gateway-network UUID derived from GATEWAY_NAME
+#      so the same project name always produces the same gateway identity.
+#
+# NOTE on commissioning: we deliberately do NOT write commissioning.json={}.
+# Doing so bypasses env-driven commissioning, which means
+# ACCEPT_IGNITION_EULA / GATEWAY_ADMIN_PASSWORD / IGNITION_EDITION are
+# ignored and the gateway boots with no admin user. The sentinel file alone
+# prevents this script from re-seeding on container restart.
+set -e
+
+DATA_DIR="/data"
+TEMPLATE_SRC="/template-source"
+
+if [ ! -f "${DATA_DIR}/.ignition-seed-complete" ]; then
+  echo "Seeding data for gateway..."
+
+  # Copy base ignition data into the persistent volume.
+  cp -dpR /usr/local/bin/ignition/data/* "${DATA_DIR}/"
+
+  # Layer the project's resources and projects on top.
+  if [ -d "${TEMPLATE_SRC}/config/resources" ]; then
+    echo "Copying resources from ${TEMPLATE_SRC}/config/resources -> ${DATA_DIR}/config/resources"
+    mkdir -p "${DATA_DIR}/config/resources"
+    cp -R "${TEMPLATE_SRC}/config/resources/." "${DATA_DIR}/config/resources/"
+  fi
+  if [ -d "${TEMPLATE_SRC}/projects" ]; then
+    echo "Copying projects from ${TEMPLATE_SRC}/projects -> ${DATA_DIR}/projects"
+    mkdir -p "${DATA_DIR}/projects"
+    cp -R "${TEMPLATE_SRC}/projects/." "${DATA_DIR}/projects/"
+  fi
+
+  # Drop any cached artifacts from the modules cache into the gateway.
+  # The compose engine mounts <project>/modules/cache to /modules-cache:ro
+  # for any gateway that lists modules or JDBC drivers; gateways without
+  # any skip this block harmlessly. Third-party .modl files go to
+  # user-lib/modules (the companion ACCEPT_MODULE_* env vars on the gateway
+  # service tell Ignition to trust + load them on boot); JDBC .jar drivers
+  # go to user-lib/jdbc where the gateway's driver configs expect them.
+  if [ -d "/modules-cache" ]; then
+    echo "Dropping cached .modl modules from /modules-cache -> ${DATA_DIR}/user-lib/modules"
+    mkdir -p "${DATA_DIR}/user-lib/modules"
+    cp /modules-cache/*.modl "${DATA_DIR}/user-lib/modules/" 2>/dev/null || true
+    echo "Dropping cached .jar drivers from /modules-cache -> ${DATA_DIR}/user-lib/jdbc"
+    mkdir -p "${DATA_DIR}/user-lib/jdbc"
+    cp /modules-cache/*.jar "${DATA_DIR}/user-lib/jdbc/" 2>/dev/null || true
+  fi
+
+  # Hand ownership of everything in /data to the ignition user (uid 2003)
+  # so the gateway can write its .resources/ caches and any UI-driven changes.
+  chown -R 2003:2003 "${DATA_DIR}"
+
+  # Deterministic gateway-network UUID derived from GATEWAY_NAME.
+  UUID=$(echo -n "${GATEWAY_NAME}" | md5sum | awk '{print $1}' | sed 's/\(........\)\(....\)\(....\)\(....\)\(............\)/\1-\2-\3-\4-\5/' | tr -d '[:space:]')
+  mkdir -p "${DATA_DIR}/config/local/ignition/gateway-network"
+  echo -n "${UUID}" > "${DATA_DIR}/config/local/ignition/gateway-network/uuid.txt"
+  echo "Generated UUID for gateway: ${UUID}"
+
+  touch "${DATA_DIR}/.ignition-seed-complete"
+
+  echo "Seeding complete for gateway."
+else
+  echo "Gateway already seeded, skipping..."
+fi
+
+echo "Bootstrap completed successfully."

ignition_stack/templates/standalone-postgres/services/ignition/config/resources/core/config-mode.json

@@ -0,0 +1,7 @@
+{
+  "title": "Core",
+  "description": "Core collection of locally managed Gateway configuration resources",
+  "enabled": true,
+  "inheritable": true,
+  "parent": "external"
+}

ignition_stack/templates/standalone-postgres/services/ignition/config/resources/dev/config-mode.json

@@ -0,0 +1,7 @@
+{
+  "title": "Development",
+  "description": "",
+  "enabled": true,
+  "inheritable": true,
+  "parent": "core"
+}

ignition_stack/wizard.py

@@ -0,0 +1,362 @@
+"""Interactive wizard that walks the architecture decision tree.
+
+The wizard's *core* (``walk()``) is a pure function over a small
+:class:`Prompter` protocol. Real CLI invocations pass a
+:class:`QuestionaryPrompter` that delegates to ``questionary``; tests pass
+a :class:`ScriptedPrompter` with a pre-recorded sequence of answers and
+assert on the resulting :class:`ProjectConfig`. Wizard logic stays
+testable without a TTY this way.
+
+The UX shape borrows from Create T3 App: select -> defaults -> summary ->
+generate. Each step is one Questionary prompt; the summary screen
+recaps the resolved choices and a single confirm gates the write.
+
+Step order:
+
+1. **Profile** - which of the four canned shapes the user wants.
+2. **Profile-specific** - spoke count for hub-and-spoke (skipped elsewhere).
+3. **Database** - SQL flavor for the stack, or "none".
+4. **Edition per role** - which role (if any) runs Edge. The default is
+   profile-driven: scaleout proposes "frontend", hub-and-spoke proposes
+   "spoke (all spokes)", standalone and mcp-n8n propose "none".
+5. **Reverse proxy** - existing/install-Traefik/skip.
+6. **Summary + confirm**.
+
+Per-gateway env-var overrides (``memory_mb`` etc.) are deferred to Phase 7
+when the lifecycle/reset commands need them; the gateway model already
+accepts them, so adding a wizard step on top is a non-breaking follow-up.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from ignition_stack.config import ProjectConfig, ReverseProxyConfig
+from ignition_stack.profiles import (
+    ProfileError,
+    ProfileOptions,
+    build_profile,
+    list_profiles,
+)
+
+# Database options shown in the wizard, in the order they appear on screen.
+_DB_CHOICES: list[tuple[str, str]] = [
+    ("postgres", "Postgres (recommended)"),
+    ("mysql", "MySQL"),
+    ("mariadb", "MariaDB"),
+    ("mongo", "MongoDB"),
+    ("none", "No database (gateway-only stack)"),
+]
+
+# Per-profile default edge-role proposal. The wizard offers this as the
+# default selection in the edition prompt; the user can override.
+_DEFAULT_EDGE_ROLE: dict[str, str] = {
+    "standalone": "none",
+    "scaleout": "frontend",
+    "hub-and-spoke": "spoke",
+    "mcp-n8n": "none",
+}
+
+
+class Prompter(Protocol):
+    """Minimal prompt surface the wizard uses.
+
+    Implementations: :class:`QuestionaryPrompter` (real CLI) and the test
+    harness's ``ScriptedPrompter``. Keeping the surface this small keeps
+    the wizard easy to mock and easy to reason about.
+    """
+
+    def select(
+        self,
+        message: str,
+        choices: Sequence[tuple[str, str]],
+        default: str | None = None,
+    ) -> str:
+        """Single-choice prompt. ``choices`` is a list of ``(value, label)``
+        pairs; the chosen ``value`` is returned. ``default`` is one of the
+        values (or None for first-choice default)."""
+
+    def text(
+        self,
+        message: str,
+        default: str = "",
+    ) -> str:
+        """Free-text prompt; returns the user's string (or ``default``)."""
+
+    def confirm(self, message: str, default: bool = False) -> bool:
+        """Yes/no prompt; returns the user's choice (or ``default``)."""
+
+    def integer(self, message: str, default: int, minimum: int = 0) -> int:
+        """Integer prompt; validates ``>= minimum`` and returns the parsed value."""
+
+
+@dataclass
+class WizardOutcome:
+    """What the wizard produces.
+
+    The :class:`ProjectConfig` is the headline output; ``confirmed`` lets
+    the caller distinguish "user reviewed the summary and said yes" from
+    "user bailed at the summary" so the CLI can exit non-zero cleanly.
+    """
+
+    config: ProjectConfig
+    confirmed: bool
+    profile: str
+    options: ProfileOptions
+    summary_lines: list[str] = field(default_factory=list)
+
+
+def run_wizard(name: str, prompter: Prompter | None = None) -> ProjectConfig:
+    """Run the wizard. Used by the CLI; raises if the user cancels at the summary.
+
+    ``prompter`` defaults to a :class:`QuestionaryPrompter`. Tests pass a
+    scripted prompter to drive the wizard without a TTY.
+    """
+    if prompter is None:
+        prompter = QuestionaryPrompter()
+    outcome = walk(name, prompter)
+    if not outcome.confirmed:
+        raise KeyboardInterrupt("wizard cancelled at summary")
+    return outcome.config
+
+
+def walk(name: str, prompter: Prompter) -> WizardOutcome:
+    """Walk the decision tree and return the resolved config + summary.
+
+    Pure modulo the prompter; no I/O, no global state. Profile validation
+    happens once, at the end - red-tier hub-and-spoke advisories surface as
+    :class:`ProfileError`, which the CLI catches.
+    """
+    profile_slug = _ask_profile(prompter)
+    spokes = _ask_spokes(prompter) if profile_slug == "hub-and-spoke" else 3
+    db_kind = _ask_database(prompter)
+    edge_role = _ask_edge_role(prompter, profile_slug)
+    reverse_proxy = _ask_reverse_proxy(prompter)
+
+    options = ProfileOptions(
+        spokes=spokes,
+        force=False,  # the wizard prompts on yellow/red instead of using --force.
+        edge_role=edge_role,
+        reverse_proxy=reverse_proxy,
+        database_kind=db_kind,
+    )
+
+    # Hub-and-spoke advisory: ask the user inside the wizard rather than
+    # demanding --force. Yellow asks for confirmation, red asks for the
+    # acknowledgement first and then proceeds via the ``force=True`` path so
+    # the profile's red-tier guard doesn't block them.
+    if profile_slug == "hub-and-spoke":
+        options = _confirm_advisory_if_needed(prompter, options)
+
+    try:
+        config = build_profile(profile_slug, name, options)
+    except ProfileError as exc:
+        # Only happens if the user declined the red-tier confirmation;
+        # treat as an explicit cancel.
+        return WizardOutcome(
+            config=ProjectConfig(name=name),
+            confirmed=False,
+            profile=profile_slug,
+            options=options,
+            summary_lines=[f"advisory: {exc}"],
+        )
+
+    summary = _summarize(config, profile_slug, options)
+    confirmed = _ask_summary_confirm(prompter, summary)
+    return WizardOutcome(
+        config=config,
+        confirmed=confirmed,
+        profile=profile_slug,
+        options=options,
+        summary_lines=summary,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Step implementations
+# --------------------------------------------------------------------------- #
+
+
+def _ask_profile(prompter: Prompter) -> str:
+    choices = [(p.slug, f"{p.slug:<14} - {p.summary}") for p in list_profiles()]
+    return prompter.select("Architecture profile?", choices, default="standalone")
+
+
+def _ask_spokes(prompter: Prompter) -> int:
+    return prompter.integer("Spoke gateway count?", default=3, minimum=0)
+
+
+def _ask_database(prompter: Prompter) -> str | None:
+    raw = prompter.select("Database?", _DB_CHOICES, default="postgres")
+    return None if raw == "none" else raw
+
+
+def _ask_edge_role(prompter: Prompter, profile_slug: str) -> str | None:
+    choices = _edition_choices_for(profile_slug)
+    if not choices:
+        return None
+    default = _DEFAULT_EDGE_ROLE.get(profile_slug, "none")
+    raw = prompter.select("Run the Edge edition on which role?", choices, default=default)
+    return None if raw == "none" else raw
+
+
+def _edition_choices_for(profile_slug: str) -> list[tuple[str, str]]:
+    """The set of roles that can be Edge-ified per profile, plus 'none'."""
+    if profile_slug == "scaleout":
+        return [
+            ("none", "All gateways run standard"),
+            ("frontend", "Frontend runs Edge (recommended for scaleout)"),
+            ("backend", "Backend runs Edge"),
+        ]
+    if profile_slug == "hub-and-spoke":
+        return [
+            ("none", "All gateways run standard"),
+            ("spoke", "All spokes run Edge (recommended for hub-and-spoke)"),
+            ("hub", "Hub runs Edge (unusual; spokes stay standard)"),
+        ]
+    # standalone / mcp-n8n: single gateway
+    return [
+        ("none", "Standard edition"),
+        ("gateway", "Edge edition"),
+    ]
+
+
+def _ask_reverse_proxy(prompter: Prompter) -> ReverseProxyConfig | None:
+    choice = prompter.select(
+        "Reverse proxy?",
+        [
+            ("external", "I already run one (Traefik, nginx, ...): plain host-port mapping"),
+            ("install", "Install ia-eknorr/traefik-reverse-proxy"),
+            ("skip", "Skip - the gateway is exposed directly on a host port"),
+        ],
+        default="external",
+    )
+    if choice != "install":
+        return None
+    path = prompter.text(
+        "Where should the proxy live? (relative path under the project)",
+        default="reverse-proxy",
+    )
+    return ReverseProxyConfig(kind="traefik", path=path)
+
+
+def _confirm_advisory_if_needed(prompter: Prompter, options: ProfileOptions) -> ProfileOptions:
+    """Surface yellow/red advisories during the wizard run.
+
+    Green tier proceeds silently. Yellow asks for confirmation; declining
+    rolls back to ``spokes=4`` (still green) so the wizard doesn't strand
+    the user on a config they didn't want. Red asks the user to explicitly
+    acknowledge the cost; on confirmation, we set ``force=True`` so the
+    profile builder lets the config through.
+    """
+    from ignition_stack.profiles import spoke_advisory
+
+    advisory = spoke_advisory(options.spokes)
+    if advisory.tier == "green":
+        return options
+    if advisory.tier == "yellow":
+        confirmed = prompter.confirm(f"{advisory.message}\nProceed?", default=False)
+        if confirmed:
+            return options
+        # Step down to the largest still-green count (4) so the user lands
+        # on a usable stack instead of bailing the whole wizard.
+        return _with(options, spokes=4)
+    # red
+    confirmed = prompter.confirm(
+        f"{advisory.message}\nAcknowledge and continue anyway?", default=False
+    )
+    return _with(options, force=True) if confirmed else _with(options, spokes=4)
+
+
+def _with(options: ProfileOptions, **changes: Any) -> ProfileOptions:
+    """Return a new ProfileOptions with ``changes`` applied (frozen dataclass)."""
+    from dataclasses import replace
+
+    return replace(options, **changes)
+
+
+def _summarize(config: ProjectConfig, profile_slug: str, options: ProfileOptions) -> list[str]:
+    lines = [
+        f"profile      : {profile_slug}",
+        f"project name : {config.name}",
+        f"gateways     : {len(config.gateways)} "
+        f"({', '.join(f'{g.name}={g.ignition_edition}' for g in config.gateways)})",
+        f"database     : {config.database.kind if config.database else 'none'}",
+        f"services     : {', '.join(config.services) if config.services else '(none)'}",
+        f"network split: {'on' if config.network_split else 'off'}",
+        "reverse proxy: "
+        + (
+            f"install Traefik at './{config.reverse_proxy.path}'"
+            if config.reverse_proxy
+            else "external (plain host-port mapping)"
+        ),
+    ]
+    if config.mcp_dropin:
+        lines.append("MCP dropin   : modules/dropin/ (EA-gated; see POST-SETUP.md)")
+    if options.force:
+        lines.append("advisory     : --force acknowledged")
+    return lines
+
+
+def _ask_summary_confirm(prompter: Prompter, summary: list[str]) -> bool:
+    block = "\n".join(summary)
+    return prompter.confirm(f"Ready to generate?\n\n{block}\n", default=True)
+
+
+# --------------------------------------------------------------------------- #
+# Concrete prompter backed by Questionary
+# --------------------------------------------------------------------------- #
+
+
+class QuestionaryPrompter:
+    """Real-CLI prompter that delegates to ``questionary``.
+
+    Each method translates the Prompter contract into the equivalent
+    Questionary call. Imported lazily so unit tests don't require a TTY.
+    """
+
+    def select(
+        self,
+        message: str,
+        choices: Sequence[tuple[str, str]],
+        default: str | None = None,
+    ) -> str:
+        import questionary
+
+        # Questionary's `select` takes a list of `Choice` objects with a
+        # title (what the user sees) and a value (what we receive). Build
+        # the map so we can resolve the answer back to its slug.
+        q_choices = [questionary.Choice(title=label, value=value) for value, label in choices]
+        # Questionary matches `default` against choice values, not titles, so
+        # pass the slug straight through (or None when it isn't a real choice).
+        default_value = default if any(value == default for value, _ in choices) else None
+        answer = questionary.select(message, choices=q_choices, default=default_value).unsafe_ask()
+        return str(answer)
+
+    def text(self, message: str, default: str = "") -> str:
+        import questionary
+
+        answer = questionary.text(message, default=default).unsafe_ask()
+        return str(answer)
+
+    def confirm(self, message: str, default: bool = False) -> bool:
+        import questionary
+
+        return bool(questionary.confirm(message, default=default).unsafe_ask())
+
+    def integer(self, message: str, default: int, minimum: int = 0) -> int:
+        import questionary
+
+        def _validate(text: str) -> bool | str:
+            try:
+                value = int(text)
+            except ValueError:
+                return "Enter an integer."
+            if value < minimum:
+                return f"Must be >= {minimum}."
+            return True
+
+        answer = questionary.text(message, default=str(default), validate=_validate).unsafe_ask()
+        return int(answer)

ignition_stack-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: ignition-stack
+Version: 0.1.0
+Summary: CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements
+Author-email: Ethan Knorr <eknorr@inductiveautomation.com>
+License: Apache-2.0
+Keywords: compose,docker,ignition,sales-engineering,scada
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: psutil>=5.9
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.7
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Provides-Extra: poc
+Requires-Dist: httpx>=0.27; extra == 'poc'
+Requires-Dist: playwright>=1.49; extra == 'poc'
+Description-Content-Type: text/markdown
+
+# ignition-stack
+
+[![CI](https://github.com/ia-eknorr/ignition-stack/actions/workflows/ci.yml/badge.svg)](https://github.com/ia-eknorr/ignition-stack/actions/workflows/ci.yml)
+[![Docs](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml/badge.svg)](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml)
+[![Documentation](https://img.shields.io/badge/docs-ia--eknorr.github.io-blue)](https://ia-eknorr.github.io/ignition-stack/)
+
+CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Picks an architecture profile, asks a few questions, writes a self-contained project with a hand-readable compose file, env, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
+
+See [`docs/docs/reference/seeding-matrix.md`](docs/docs/reference/seeding-matrix.md) for which Ignition 8.3 connection types can be provisioned from the filesystem and env on a live 8.3.6 gateway. Full documentation lives in the [`docs/`](docs/) Docusaurus site.
+
+## Install
+
+```sh
+pipx install ignition-stack
+```
+
+To install from source instead of PyPI - the latest off `main`, or a specific branch:
+
+```sh
+pipx install git+https://github.com/ia-eknorr/ignition-stack.git
+pipx install git+https://github.com/ia-eknorr/ignition-stack.git@<branch>
+```
+
+## Quickstart
+
+Generate a project and bring it up:
+
+```sh
+ignition-stack init demo
+cd demo
+docker compose up -d
+```
+
+The gateway reaches RUNNING with no UI prompts. The admin user is `admin / password` and the gateway is at `http://localhost:9088`. The default Postgres credentials are `ignition / ignition` on the `db` service.
+
+Everything that ships in the generated project is hand-readable: `docker-compose.yaml`, `.env`, `scripts/docker-bootstrap.sh`, and a `services/ignition/` resources tree the gateway reads on first boot.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init <name>` | Generate a project at `./<name>/` from a profile and a few prompts. |
+| `modules` | Download, verify, and manage the `.modl` / JDBC catalog. |
+| `reset` | Re-run generation from an SE-demo project's recorded config. |
+| `switch-profile` | Reshape an SE-demo project under a different profile. |
+| `wipe` | Remove this project's containers and volumes only. |
+
+See the [CLI reference](docs/docs/reference/cli.md) for every command, argument, and option.
+
+## What gets generated
+
+```
+demo/
+  docker-compose.yaml         # one gateway, one Postgres, one bootstrap init container
+  .env                        # values referenced by docker-compose.yaml
+  scripts/
+    docker-bootstrap.sh       # seeds /data, sets gateway-network UUID, hands ownership to uid 2003
+  services/
+    ignition/
+      config/resources/core/config-mode.json
+      config/resources/dev/config-mode.json
+      projects/.gitkeep
+```
+
+The bootstrap script is run once per data volume. It copies the gateway's base data into a named volume, layers the project's `services/ignition/` tree on top, sets a deterministic gateway-network UUID derived from the project name, and hands ownership of `/data` to uid 2003 so the gateway can write its resource caches.
+
+Commissioning is fully env-driven (`ACCEPT_IGNITION_EULA=Y`, `GATEWAY_ADMIN_PASSWORD`, `IGNITION_EDITION`), so first boot needs no UI.