MiniStack + StackPort: a local AWS development handbook

The pairing is easy to misread as one product. It is not. MiniStack is an emulator: a Python ASGI application that speaks the AWS wire protocols and answers as though it were AWS. StackPort is a read/write client: a FastAPI backend wrapping boto3, plus a React single-page app, that renders whatever the emulator holds. StackPort has no privileged channel — it is just another SDK caller, subject to exactly the same signing rules as your own code.

That distinction is the single most useful thing to hold onto while debugging, because it predicts where faults live. If the UI shows an error, the question is never immediately is the emulator broken — it is did StackPort manage to sign and send a request at all. On a clean install the answer is often no, and MiniStack never sees the traffic.

MiniStack's pitch is breadth and speed: roughly 80 services on one port, sub-two-second startup, and real backends where a mock would be useless — DuckDB behind Athena, actual Postgres and MySQL containers behind RDS, real Redis behind ElastiCache, and an optional passthrough that turns Bedrock calls into an OpenAI-compatible request against Ollama or vLLM. It is a drop-in for Terraform, CDK, Pulumi and Testcontainers, and deliberately mirrors LocalStack's flag names and health endpoints so existing tooling keeps working.

StackPort's pitch is visibility. Emulators are opaque: you create resources through an SDK and then have no idea what is in there. StackPort browses 35 services, with purpose-built UIs for the eight you poke at most — S3, DynamoDB, Lambda, SQS, IAM, EC2, CloudWatch Logs and Secrets Manager — plus a generic table-and-JSON browser for the other 27. It also runs against LocalStack, Moto, and real AWS accounts, which is why it defaults to allowing writes locally but ships a STACKPORT_ALLOW_WRITES=false switch for anything you would rather not damage.

What neither tool promises is fidelity. An emulator that implements 80 services implements the common paths of 80 services. IAM does not really enforce policies, signatures are never verified, and error shapes drift from real AWS in the corners. Treat it as a fast feedback loop for wiring and shape-checking, not as proof that a deployment will behave.

Real AWS gives every service its own hostname. MiniStack collapses all of them onto :4566, which means the very first thing it must do on every request is work out which service you meant. That decision lives in detect_service() in ministack/core/router.py, and it tries six signals in order, returning on the first hit.

The ordering is not cosmetic — it encodes which signals are trustworthy. A X-Amz-Target header is unambiguous, so it wins. The credential scopeCredential scopeThe date/region/service/aws4_request path inside a SigV4 credential. inside the SigV4SigV4AWS Signature Version 4, the request-signing scheme every SDK uses. Authorization header is next, because every signed SDK request carries the service's signing name whether or not it sets a target header. Only after those does the router fall back to weaker hints: an Action query parameter, a path pattern, then a Host regex.

Two consequences are worth internalising. First, step six is a catch-all to S3: anything that matches nothing is handed to the S3 handler, mirroring LocalStack. This is why a malformed or unsigned request so often produces a baffling S3 error rather than a helpful one — the router did not fail, it defaulted. Second, because host-pattern matching iterates a dictionary in declaration order and takes the first regex hit, entry order is load-bearing. The source carries an explicit comment about this: dynamodbstreams is declared before dynamodb because the host streams.dynamodb.<region>.amazonaws.com matches both patterns, and without that ordering Streams traffic would be silently misrouted.

Behind the router, handlers are lazy-loaded — a service's module is imported the first time a request selects it. That is what keeps startup under two seconds despite the breadth, and it means an unused service costs nothing but a routing-table entry.

Some services then reach outward. RDS, DSQL, ElastiCache, EKS, OpenSearch and Lambda can each spawn real Docker containers, which is why the compose file mounts /var/run/docker.sock. Those containers publish on host ports allocated from a per-service base — RDS_BASE_PORT=15432, ELASTICACHE_BASE_PORT=16379, DSQL_BASE_PORT=25432 — incrementing per instance. When MiniStack itself runs in a container and needs to talk to those, set DOCKER_NETWORK to your compose network so names resolve.

The fastest correct path is one compose file holding both containers plus Redis, because it removes the two things people get wrong by hand: the credentials StackPort needs, and the hostname it uses to reach the emulator. Inside a compose network, StackPort addresses MiniStack as http://ministack:4566 — no host.docker.internal involved, which is the detail that makes the same file work identically on both platforms.

Prerequisites differ only in how you obtain them. On macOS you need Docker Desktop (the engine runs in a Linux VM — there is no native option) and the AWS CLI, most easily brew install awscli. On Ubuntu you can run native Docker Engine from apt, which avoids the VM entirely; install the AWS CLI with the official script rather than apt, because apt install awscli still ships v1 and this handbook assumes v2 behaviour throughout.

One Ubuntu-specific trap: after installing Docker Engine your user is not in the docker group, so every command needs sudo until you run sudo usermod -aG docker $USER and start a new login session. A second: if you ever depart from compose and wire containers together by hand, host.docker.internal does not resolve on native Engine the way it does on Docker Desktop — you need extra_hosts: ["host.docker.internal:host-gateway"], or better, keep using service names.

Verify with the health endpoint rather than by opening the UI, so you are testing one thing at a time. curl http://localhost:4566/_ministack/health returns a JSON map of every service to available, plus version, edition and the status of any startup scripts. The edition field is worth reading: the light image omits optional native dependencies, and that omission is the direct cause of the checksum failure in §7. LocalStack-compatible aliases /_localstack/health and /health answer the same way, so existing wait-for-it scripts keep working.

Only once the emulator answers should you open StackPort at http://localhost:8080. If the dashboard populates, both halves and the credentials between them are correct.

There are three ways to aim the CLI at a local endpoint, and the commonly documented one is now the worst. Passing --endpoint-url on every command works but is tedious; exporting AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION avoids a profile but leaks into every shell you forget about.

The better option, available since AWS CLI 2.13, is to put `endpoint_url`endpoint_url (profile setting)Puts the target endpoint in ~/.aws/config so no flag is needed. inside the profile so no flag or variable is needed at all. A complete working profile has four parts: the endpoint, a region, dummy credentials, and two settings that exist purely to work around modern-CLI defaults.

The first workaround is checksums, and it is the one that will bite you. AWS CLI ≥ 2.23 defaults request_checksum_calculation to when_supported, which picks CRC64NVMECRC64NVMEThe checksum algorithm AWS SDKs began defaulting to, which MiniStack rejects. for S3 uploads. MiniStack rejects it — the light image does not bundle the native dependency — with InvalidRequest: Checksum algorithm not supported in this ministack build: CRC64NVME. Setting request_checksum_calculation = when_required omits the checksum unless an API mandates one, and uploads start working. Note that reads and every other service are unaffected, so the symptom looks weirdly specific to s3 cp.

The second is addressing style. Set addressing_style = path, because virtual-hosted-style would resolve my-bucket.localhost, and there is no wildcard DNS for localhost. MiniStack does implement virtual-hosted-styleVirtual-hosted-stylehttp://bucket.host/key — bucket promoted into the hostname. extraction for clients that use it, but path-stylePath-style addressinghttp://host/bucket/key — bucket in the path, not the hostname. is what its own tooling assumes.

Decide deliberately whether this becomes your [default] profile. Making it the default means bare aws s3 ls just works, and on a machine with no real AWS credentials that is also a safety win — a stray destructive command cannot reach a real account. The moment you add real credentials, put them in a named profile so bare commands keep hitting localhost. Two smaller gotchas worth naming: the config files are INI read by the CLI, so source ~/.aws/config accomplishes nothing, and aws s3 cp requires exactly one side to carry the s3:// scheme — aws s3 cp file my-bucket fails with ParamValidation because the CLI sees two local paths.

The repository also ships an `awslocal`awslocalA thin wrapper that injects dummy credentials and the local endpoint. wrapper that exports dummy credentials and appends --endpoint-url. It is convenient, but a wrapper that predates the checksum default will fail on uploads for exactly the reason above unless it also exports AWS_REQUEST_CHECKSUM_CALCULATION — worth checking before you trust it.

StackPort is a single container: a FastAPI backend that builds cached boto3 clients, a thread-safe TTL cache, a WebSocket probe loopProbe loopStackPort's periodic per-service health sweep that feeds the live dashboard. feeding the live dashboard, and a React SPA served as static files from the same process. Routes are grouped per service under /api/..., with /ws carrying dashboard updates. A healthy handshake on /ws answers 101 Switching Protocols.

The trap is that AWS_ENDPOINT_URL alone is not enough. Point the container at MiniStack with only that variable and every call fails with botocore.exceptions.NoCredentialsError: Unable to locate credentials, surfacing in the browser as a bare 500 on /api/s3/buckets. The reason is worth being precise about: botocore fails while signing, before opening a socket. No request reaches MiniStack, so nothing appears in its logs, and the emulator looks guilty while being entirely uninvolved.

It also cannot borrow your credentials. A container does not see the host's ~/.aws, so the profile you configured for the CLI is invisible to it. Either pass AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY directly — any values work, since MiniStack never verifies signatures — or mount ~/.aws:/root/.aws and set AWS_PROFILE. Upstream's own example compose file passes test/test explicitly, which is the strongest hint about the intended usage.

Beyond the basics, the configuration surface is mostly about scope and safety. STACKPORT_ENDPOINTS registers several targets in one string (local=http://localhost:4566,nprod=, where an empty value means real AWS), and per-endpoint auth supports SSO, AssumeRole and static keys from the Settings UI — when an SSO token expires you get a 401 telling you to run aws sso login. STACKPORT_SERVICES trims the probe list so the dashboard stops checking services you do not use, and STACKPORT_ALLOW_WRITES=false turns the whole thing read-only, which is the setting to reach for the moment an endpoint points anywhere real. Endpoints added through the UI persist to endpoints.json under STACKPORT_DATA_DIR, so mount it if you want them to survive.

There is also a CLI in the same package — stackport status, list, describe, export, each accepting --endpoint and --region and emitting JSON, CSV or tables. For scripted inspection it is usually faster than the UI, and it makes the tool useful in CI where nobody is looking at a browser.

MiniStack is in-memory first. S3_PERSIST defaults to 0, and the S3 module says so in its own docstring: storage is in-memory, optionally backed by S3_DATA_DIR. Objects live in the Python process heap, so stopping the container — not deleting it, merely stopping it — frees them. The tell is unambiguous: a compose file can mount ./data/s3 and that directory stays completely empty, because nothing was ever written to it.

Flip S3_PERSIST=1 and objects are written through to S3_DATA_DIR, laid out account-scoped as <account_id>/<bucket>/<key> — so a bucket created under the default account lands in data/s3/000000000000/<bucket>/. The path resolution is hardened against traversal: keys containing .. are rejected rather than allowed to escape the data directory. Persistence is per-subsystem, with PERSIST_STATE for general service state and RDS_PERSIST / DSQL_PERSIST switching those containers from tmpfs to Docker named volumes.

The trade-off runs the other way too. Persisted data survives docker compose down and the /_ministack/reset control endpoint, so stale fixtures leak between test runs and eventually produce failures that make no sense. Either clear the directory deliberately, or leave persistence off and treat every start as clean — the default exists for a reason.

For the container filesystem itself, the layers are worth separating. A bind mountBind mountA host directory mapped into a container, as opposed to a named volume. like ./data/s3:/tmp/ministack-data/s3 maps to a real directory you can open in your editor. Named volumes and each container's writable layer live under Docker's own root, which docker info reports as /var/lib/docker. On Ubuntu that is a genuine host path. On macOS it is a path inside the Linux VM, and the whole VM is one sparse disk image at ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw — which will happily report a 460 GB apparent size while occupying under a gigabyte, because it allocates lazily. Only bind mounts escape that image into somewhere Finder can reach.

The practical rule: if you want to read, grep or edit emulator data with ordinary tools, it must be on a bind mount, and persistence must be switched on. Everything else is either RAM or inside a VM image.

Six distinct failures showed up while bringing this stack up from nothing on macOS. Five were configuration plumbing and one was a genuine packaging gap in a helper script. None were emulation bugs — which is the pattern worth expecting.

What makes them expensive is misattribution. The checksum rejection names an algorithm you never chose. The StackPort 500 implicates the emulator when the emulator was never contacted. The NoCredentials error on a bare command appears after you have already configured a working profile. In each case the error text is accurate about the mechanism and misleading about the cause, so the useful habit is to ask which component actually emitted it before changing anything.

Two of them share a root: modern AWS SDK defaults moving faster than emulators. CRC64NVME checksums became the default in botocore 1.36, and any emulator that has not added the native dependency now rejects uploads from a stock, up-to-date CLI. Expect more of this shape, and expect the fix to be a client-side default rather than an emulator patch.

The table below is sorted by where each failure surfaces. Every symptom string is quoted from an actual run.

MiniStack exposes a small control plane under /_ministack/ that is more useful than restarting containers. GET health reports per-service availability, version, edition and startup-script status. POST reset wipes all state without a restart, and POST reset?init=1 re-runs the startup scripts afterwards — the fast way to return to a known fixture between test runs. POST config adjusts settings live. Two inspection endpoints save real time: GET ses/messages reads the emails SES captured in memory, and GET sqs/messages peeks at a queue without consuming, both filterable by account.

Startup scripts are how you get repeatable fixtures. MiniStack honours LocalStack's directories — /etc/localstack/init and /docker-entrypoint-initaws.d — so mounting a folder of shell scripts there provisions your buckets, tables and queues on boot, and reset?init=1 replays them.

Multi-tenancy needs no configuration and is easy to trigger by accident. If AWS_ACCESS_KEY_ID is 12 digits, that value becomes the account id in every ARN; anything non-numeric like test falls back to MINISTACK_ACCOUNT_ID, default 000000000000. So switching your dummy key from test to 111111111111 silently moves you into a different tenant with its own resources — occasionally exactly what you want for isolation tests, occasionally a very confusing empty bucket list. Regions work the same way, taken from the request's credential scope, so --region eu-west-1 and --region us-east-1 address genuinely separate resource sets.

For stopping, distinguish the two verbs. docker compose stop halts containers but keeps them, so start resumes quickly; docker compose down removes them and needs a full up. Either way, with persistence off, the data is gone — the containers surviving is not the same as the state surviving. If StackPort was launched by hand with docker run rather than through compose, compose commands will not touch it and it must be stopped by name; folding it into the compose file behind an opt-in profile is what makes one command handle everything.

Finally, keep the emulator's own test suite in mind as documentation. The repository ships some 1,400 tests across the services, and when you are unsure whether a behaviour is supported, the test for it is a faster and more honest answer than the README.