Local AWS with MiniStack
Provision real AWS resources with OpenTofu against MiniStack, a local emulator that runs real ECS, RDS and ElastiCache containers. No AWS account needed.
MiniStack is an AWS emulator under the MIT license. Most API mocks only answer calls; MiniStack also starts real containers for ECS tasks, RDS and ElastiCache. A deployment against it runs the same OpenTofu modules, the same state handling and the same health checks as a deployment against a real account.
Docker socket
MiniStack needs the Docker socket to start those containers, which gives it control of your Docker daemon. Use it on a development machine only.
Start MiniStack
The quickstart compose command already includes the aws-emulator
profile. If you run the apps on the host instead, start MiniStack on its own:
pnpm local:aws # docker compose ... --profile aws-emulator up -d --wait ministackMiniStack listens on http://localhost:4566. Inside the compose network its address is
http://ministack:4566, and the containers it starts join the same network.
The seeded target
The seed registers an AWS cloud target named Local AWS (MiniStack):
{
"accountId": "000000000000",
"emulator": "ministack",
"endpointUrl": "http://localhost:4566",
"runnerEndpointUrl": "http://ministack:4566",
"dnsZone": "orkstage.local",
"createDnsZone": true
}| Field | Meaning |
|---|---|
emulator | Switches to the emulator's static test credentials and endpoint overrides. |
endpointUrl | The AWS endpoint as the API and worker processes reach it. |
runnerEndpointUrl | The same endpoint as OpenTofu runner containers reach it. |
dnsZone, createDnsZone | The platform DNS zone for instance subdomains. On the emulator, OrkStage creates it on first use. |
In the compose stack, the worker also sets AWS_EMULATOR_ENDPOINT=http://ministack:4566. Links in
the console keep http://localhost:4566, so your browser can open them.
Deploy the staging instance
Validate the target
Open Cloud targets, then Local AWS (MiniStack), and click Validate. Validation checks the emulator credentials, account access and the OpenTofu state bucket. On the emulator, OrkStage creates the bucket and turns on versioning the first time it needs it. Validation fails with a clear message when MiniStack is not running. The IAM permission probe runs on real accounts only.
Deploy
Open Instances, then Acme Staging (local AWS) (template starter-standard), and click
Deploy. The worker runs one OpenTofu container per resource step, in dependency order. Each
resource gets its own state file in MiniStack's S3.
Check what was created
| Template resource | AWS resources (OpenTofu module) |
|---|---|
network | VPC, public and private subnets, internet gateway, route tables, internal security group (optional NAT gateway) |
registry | ECR repository with scan on push, immutable tags and a lifecycle policy |
database | RDS PostgreSQL instance, subnet group, security group, Secrets Manager secret for the credentials |
cache | ElastiCache Valkey replication group, subnet group, security group |
messaging | SQS queue, plus a second queue for messages that fail processing (dead letter queue) |
api, worker | ECS cluster, task definition, service, CloudWatch log group, execution role, security group |
ingress | Application Load Balancer, target groups, HTTP listener and path rules |
dns | Route 53 record, ACM certificate with DNS validation, HTTPS listener |
MiniStack serves the ALB at http://localhost:4566/_alb/<lb-name>/. The console shows this address
as the url output of the ingress.
Mix real and simulated
You can bind only the primary slot of multicloud-reference to MiniStack and keep data (Azure)
and storage (OCI) on the simulated targets. OrkStage provisions the AWS part for real. The rest is
simulated and labelled as simulated.
Known differences from real AWS
- On a second plan, MiniStack reports changes in place for some RDS and ElastiCache attributes. Drift scans against the emulator can therefore flag changes nobody made. Treat drift on MiniStack as a hint.
- MiniStack does not emulate autoscaling. Services run their fixed
replicas, and the deployment logs a warning. - MiniStack does not serve the public SSM parameter for the Amazon ECS optimized AMI. On the
emulator,
ecs-ec2services use a placeholder AMI.
Contract tests against the emulator
MINISTACK_E2E=1 pnpm --filter @orkstage/cloud-aws test # inside orkstage/This command runs the contract suite of the AWS provider adapter (ensure, read, health, delete) against MiniStack.
Free tier accounts
Prove OrkStage against real AWS, Azure and Oracle Cloud accounts on their free offers, with the Portable starter template, a budget alert and a clean teardown.
Core concepts
The OrkStage vocabulary, from instances, templates and placement slots to cloud targets, tenant limits, deployments, health, incidents and audit.