The Problem
Developers need a fully functional, free local replica of AWS to run integration tests and CI pipelines without paying for commercial emulators or maintaining complex mocks. Existing community editions of similar tools have introduced paid tiers, leaving a gap for cost‑free, production‑grade service emulation.
What This Does
ministack bundles more than 40 AWS services into a single HTTP endpoint (http://localhost:4566). The core server lives in ministack/app.py and is launched via the package entry point ministack/main.py. Each service implementation resides under ministack/services/ (e.g., s3.py, dynamodb.py, lambdasvc.py) and follows the same request‑routing logic defined in ministack/core/router.py.
Real backing stores are used where feasible: RDS containers run actual PostgreSQL/MySQL, ElastiCache uses real Redis, and Athena executes queries through DuckDB. The Docker image (Dockerfile) is deliberately lightweight (~270 MB) and starts in under two seconds, exposing a single port (4566) for all services.
How To Use It
Setup
Python package – install from PyPI and run the CLI:
pip install ministack ministack # invokes ministack/main.py Docker image – pull and start the pre‑built container:
docker run -p 4566:4566 ministackorg/ministack Local build – clone the repo, then bring up the compose stack:
git clone https://github.com/ministackorg/ministack cd ministack docker compose up -d # uses docker-compose.yml
Configuration
Change the listening port with the environment variable GATEWAYPORT (documented in the README). For services that require host‑level Docker access (RDS, ECS, Lambda containers), bind the Docker socket as shown in the README example: -v /var/run/docker.sock:/var/run/docker.sock.
Running
The server starts automatically and listens on http://localhost:4566. Health can be verified with the internal endpoint:
curl http://localhost:4566/ministack/health Reset state between test runs via POST /ministack/reset or include init scripts with ?init=1.
All commands above are taken verbatim from the README.md and the Dockerfile.
Real‑World Use
A CI job that validates Terraform modules can spin up MiniStack, apply the plan, and destroy it without external dependencies:
steps: name: Start MiniStack run: | docker run -d -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock ministackorg/ministack curl -s http://localhost:4566/ministack/health name: Terraform apply env: AWSACCESSKEYID: test AWSSECRETACCESSKEY: test run: | terraform init terraform apply -auto-approve name: Teardown run: curl -X POST http://localhost:4566/ministack/reset
The same pattern works for pytest suites that import boto3 and target localhost:4566.
Code Health & Issues
Low – Comprehensive test suite – 74 test files covering each service (tests/test_*.py). CI workflow (.github/workflows/ci.yml) runs them on every push. Low – License present – MIT license in LICENSE. Med – Docker‑socket requirement – Real‑service emulation (RDS, ECS, Lambda) needs host Docker access, which may be a security concern in shared CI runners. Documented in the README but not gated by a runtime check. Med – Limited input validation – Service handlers (e.g., ministack/services/s3.py) trust request payloads; malformed inputs could raise uncaught exceptions. No explicit validation layer observed. Low – Dependency hygiene – requirements.txt and pyproject.toml are both present; they list compatible versions but lack a lockfile (poetry.lock or pip-tools). May lead to reproducibility drift. Low – Documentation depth – README covers start‑up and health endpoints, but advanced configuration (e.g., custom init scripts, per‑service tuning) is sparse.
No obvious structural red flags; the repository includes CI, tests, license, and a clear entry point.
The Bottom Line
MiniStack provides a free, Docker‑based local AWS emulator with real back‑ends for many services, making it a practical drop‑in replacement for paid alternatives in development and CI pipelines. It is well‑tested and easy to start, though users must accept the Docker‑socket requirement for full‑feature mode and may need to add their own input validation for production‑grade robustness. Ideal for teams needing faithful AWS behavior without licensing costs.