Compose Generation

For local execution, the generated docker-compose.yaml is the canonical local stack artifact.

It is produced from skeletons/docker-compose.skeleton.yaml.j2 by tools/sigmaxgen/sigmaxgen/generate_compose.py in the runtime repository. The generated file is marked, schema-versioned and treated as an output of the generation pipeline rather than a hand-maintained deployment manifest.

What It Generates

The Compose generator builds a complete local stack around generated components.

Generated area	Runtime repository behavior
Component services	One `sigmax-<component>` service per `composant_<name>` directory.
Dapr sidecars	One `sigmax-<component>-dapr` sidecar per component.
Storage service	A generic `sigmax-storage` service built from `storage-service/Dockerfile`.
Storage sidecar	A `sigmax-storage-dapr` sidecar for service invocation.
PostgreSQL	A `postgres:16` service with init scripts and persistent volume.
Network	A shared `internal_net` bridge network.
Volume	`postgres_data` for local database persistence.

The generated stack is intentionally local and inspectable. It lets the runtime, WASM components, Dapr sidecars, storage interpreter and database run together without baking business rules into the Rust runtime or Compose generator.

Discovery Rules

generate_compose.py discovers components by scanning the repository root for directories matching composant_<name>.

Rule	Current behavior
Component directory pattern	`composant_([a-z0-9_-]+)`
Component ordering	Sorted by directory name for deterministic output.
Image name	`localhost/sigmax-<name>:<version>`
Version source	`<component>/Version`, falling back to `0.0`.
Runtime port	Starts at `8080`, then increments per component.
Dapr HTTP port	Fixed at `3500` inside each sidecar.

Generated Topology

Component Service Shape

Each generated component service builds from its component Dockerfile, runs the generic sigMAX runtime and exposes the component runtime port.

sigmax-<name>:
  image: localhost/sigmax-<name>:<version>
  build:
    context: .
    dockerfile: composant_<name>/Dockerfile
  environment:
    SIGMAX_ROUTES: /app/generated/routes.yaml
    SIGMAX_BIND: 0.0.0.0:<runtime_port>
    DAPR_HTTP_ENDPOINT: http://sigmax-<name>-dapr:3500
    RUST_LOG: info

Field	Meaning
`SIGMAX_ROUTES`	Points the runtime to generated route metadata inside the component image.
`SIGMAX_BIND`	Binds the component runtime to its assigned local port.
`DAPR_HTTP_ENDPOINT`	Points the runtime to its paired Dapr sidecar.
`RUST_LOG`	Keeps local logs visible during generated stack execution.

The service also gets a /healthz healthcheck, joins internal_net, and exposes its runtime port to the host for local testing.

Dapr Sidecars

Every component receives a paired Dapr sidecar using docker.io/daprio/daprd:1.17.9-stablecomponents-mariner.

The sidecar is configured with:

--app-id sigmax-<name>;
--app-port <runtime_port>;
--app-protocol http;
--app-channel-address sigmax-<name>;
--dapr-http-port 3500;
--resources-path /components;
app health checks against /healthz;
read-only ./dapr/components:/components:ro mount.

This keeps service invocation explicit while preserving the component runtime as a normal HTTP process inside Compose.

Storage And Database

The Compose skeleton always includes the generic storage path.

Service	Role
`sigmax-storage`	Generic storage interpreter for `generated/storage.yaml`.
`sigmax-storage-dapr`	Dapr sidecar for storage service invocation.
`postgres`	Local PostgreSQL backing store.

sigmax-storage receives:

STORAGE_BIND: 0.0.0.0:8090
SIGMAX_STORAGE_SPEC: /app/generated/storage.yaml
DATABASE_URL: postgres://sigmax:sigmax@postgres:5432/sigmax
DAPR_HTTP_ENDPOINT: http://sigmax-storage-dapr:3500

PostgreSQL mounts postgres_data and ./postgres/init:/docker-entrypoint-initdb.d:ro, so generated SQL/init artifacts remain visible and local database state can survive container restarts.

HTTP Policy Defaults

The current skeleton defines a shared x-sigmax-http-env block for generated component services.

SIGMAX_HTTP_ALLOWED_TARGETS: "*"
SIGMAX_HTTP_TARGET_WILDCARD_BASE_URL: "*"
SIGMAX_HTTP_TARGET_WILDCARD_METHODS: GET
SIGMAX_HTTP_TARGET_WILDCARD_PATHS: "*"
SIGMAX_HTTP_TARGET_WILDCARD_TIMEOUT_MS: 3000
SIGMAX_HTTP_TARGET_WILDCARD_MAX_RESPONSE_BYTES: 65536

Safety Rules

The generator protects manual files and records what it did.

Safety behavior	Current implementation
Generated marker	The output must contain `sigMAX generated docker-compose` in the first lines.
Schema marker	The skeleton includes `schema_version: sigmax.compose/v0.1`.
Manual-file protection	A non-marked existing Compose file is not overwritten unless `force` is used.
Atomic write	Output is written through a temporary file and then replaced.
Report JSON	`generate-compose` writes status, template path, output path, components, services, warnings and errors.
Business neutrality	Tests reject hardcoded business names such as invoice-specific route or storage names.

Local Commands

The runtime repository README uses normal Docker Compose commands for local execution.

docker compose down --remove-orphans
docker compose up -d --build --force-recreate

Use the generated Compose file as evidence of the local effective stack: which component images are built, which ports are exposed, which sidecars exist, how storage is wired and which generated artifacts are mounted.

What It Is Not

Not this	Why
A hand-maintained operations manifest	It should be regenerated from the skeleton and component inventory.
A production security policy	The current wildcard HTTP defaults and local Postgres credentials are development oriented.
A business behavior file	Business behavior belongs in contracts, generated routes, generated storage and WASM artifacts.
A replacement for agreements	Agreements still record what was generated, compiled, packaged and validated.