Skip to content

Local Development Setup

Run the full Engine stack locally with Docker Compose.

Environment File

Copy the example env file and fill in secrets before starting:

cd engine
cp .env.example .env

Generate random values, for example:

openssl rand -hex 32          # JWT secrets, tokens
openssl rand -base64 32       # IDENTITY_ENCRYPTION_KEY

Required groups in .env.example:

Group Keys
Identity IDENTITY_JWT_SECRET, IDENTITY_BOOTSTRAP_ADMIN_*, IDENTITY_ENCRYPTION_KEY
RabbitMQ RABBITMQ_DEFAULT_USER, RABBITMQ_DEFAULT_PASS
Service tokens CAPABILITY_REGISTRY_TOKEN, SES_SERVICE_TOKEN, STORAGE_SERVICE_*_TOKEN
Orchestrator ORCH_RELOAD_TOKEN

Compose fails closed when required tokens are missing or still contain placeholder values.

Start the Stack

cd engine
docker-compose up -d

Verify Services

curl http://localhost:8080/v1/status
curl http://localhost:8083/healthz
curl http://localhost:8083/readyz

Common Local Ports

  • Gateway: 8080
  • Orchestrator: 8083
  • Transformers: 8081
  • Storage: 8086
  • Identity: 8088
  • RabbitMQ UI: 15672

pytest (engine tests)

cd engine
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r services/orchestrator/requirements.txt
pip install pytest pytest-asyncio httpx

python -m pytest -q tests -m "not legacy_broken"

CI runs the same suite via test.yml. See Develop and Test.

pre-commit Hook

Enable repo hooks before committing workflow changes:

git config core.hooksPath .githooks

The hook validates changed workflows and triggers (validate_workflow_headers.py, validate_triggers.py) and optionally checks dashboard JavaScript syntax when node is installed.

Reload Runtime Artifacts

After editing workflow files, reload orchestrator runtime:

curl -X POST http://localhost:8083/admin/reload \
  -H "X-Reload-Token: ${ORCH_RELOAD_TOKEN}"

Use the value from your .env (ORCH_RELOAD_TOKEN). Admin and internal OAuth routes require this header (fail-closed when ORCH_ALLOW_UNAUTH_RELOAD=false).

Template artifact files: - Place xslt_file / template_file assets under flows/artifacts/. - Kubernetes deployments mount shared flows data under /app/flows. - Runtime resolution is controlled by WORKFLOW_ARTIFACTS_DIR.

For Kubernetes environments using the artifacts PVC, sync files after updates:

./scripts/sync-flows-pv.sh meshflows-dev

Troubleshooting

  • Check logs:
docker-compose logs -f orchestrator
docker-compose logs -f gateway
  • Rebuild after dependency changes:
docker-compose build
docker-compose up -d
  • Compose refuses to start: verify all replace-with-* placeholders in .env are replaced.