Configuration

MicroStack is configured via environment variables. Emulator settings are consolidated into a strongly-typed MicroStackOptions class internally.

Environment Variables

Variable	Default	Description
`GATEWAY_PORT`	`4566`	Port to listen on
`EDGE_PORT`	`4566`	Alias for `GATEWAY_PORT` (LocalStack compatibility)
`MICROSTACK_HOST`	`localhost`	Hostname for URL generation
`MICROSTACK_REGION`	`us-east-1`	Default AWS region
`MICROSTACK_ACCOUNT_ID`	`000000000000`	Default AWS account ID
`MICROSTACK_SQS_ENDPOINT_STRATEGY`	`request`	SQS queue URL source: `request` uses the caller's scheme, host, and port; `legacy` uses `MICROSTACK_HOST` and `GATEWAY_PORT`
`PERSIST_STATE`	`0`	Set to `1` to enable JSON state persistence
`STATE_DIR`	`<temp>/microstack-state`	Directory for persisted state files
`SERVICES`	(all)	Comma-separated list of services to enable
`S3_PERSIST`	`0`	Set to `1` to enable S3 object persistence
`LOCALSTACK_PERSISTENCE`	`0`	Set to `1` to enable persistence (LocalStack compat)

Service Filtering

To start MicroStack with only specific services:

docker run -e SERVICES=sqs,s3,dynamodb -p 4566:4566 ghcr.io/damianh/microstack:latest

Service aliases are supported:

Alias	Canonical Service
`cloudwatch-logs`	`logs`
`cloudwatch`	`monitoring`
`eventbridge`	`events`
`step-functions` / `stepfunctions`	`states`
`execute-api` / `apigatewayv2`	`apigateway`
`kinesis-firehose`	`firehose`
`elbv2` / `elb`	`elasticloadbalancing`

Custom Port

docker run -e GATEWAY_PORT=5000 -p 5000:5000 ghcr.io/damianh/microstack:latest

GATEWAY_PORT controls the port inside the container. When Docker or Testcontainers maps that port dynamically, SQS queue URLs use the incoming request authority by default so SDKs can use returned URLs without rewriting them.

To retain the earlier configured-address behavior:

docker run \
  -e MICROSTACK_SQS_ENDPOINT_STRATEGY=legacy \
  -e MICROSTACK_HOST=localhost \
  -e GATEWAY_PORT=4566 \
  -p 4566:4566 \
  ghcr.io/damianh/microstack:latest

State Persistence

Enable persistence to survive restarts:

docker run -e PERSIST_STATE=1 -v ./state:/tmp/microstack-state -p 4566:4566 ghcr.io/damianh/microstack:latest

State is saved as JSON files in STATE_DIR on shutdown and restored on startup.

UI Connection

The UI is served by the gateway at /ui/ and calls the admin API on the same origin. For a custom port, publish only the gateway port:

docker run \
  -e GATEWAY_PORT=5000 \
  -p 127.0.0.1:5000:5000 \
  ghcr.io/damianh/microstack:latest

Open http://localhost:5000/ui/. MICROSTACK_UI_PORT, MICROSTACK_API_URL, and the UI host's ApiBaseUrl setting are obsolete and ignored. The admin endpoints do not grant cross-origin browser access. This is not authentication; keep these development endpoints on a trusted local network.