Ministack

Abstract

1. Introduction

LocalStack recently moved its core services behind a paid plan. If you relied on LocalStack Community for local development and CI/CD pipelines, MiniStack is your free alternative.

Free, open-source local AWS emulator. Free forever.

The reset endpoint is especially useful in CI pipelines and test suites — call it in setUp/beforeEach to get a clean environment for every test without restarting the container. Add ?init=1 to re-run your init scripts after the reset, restoring any resources they create (VPCs, queues, seed data, etc.).

2. Objective

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

This project demonstrates how Python, AWS, Docker can be applied to a real-world Blockchain & Cloud Computing problem.

4. Technology Stack

• 60+ AWS services emulated on a single port (4566)
• Drop-in compatible — works with boto3, AWS CLI, Terraform, CDK, Pulumi, any SDK
• Multi-account & multi-region — a 12-digit access key becomes the account, the SigV4 region scopes the state; isolated tenants and regions on one endpoint, like real AWS
• Amazon Bedrock locally — Converse / InvokeModel with AWS-exact wire shapes; point MINISTACK_BEDROCK_PROXY_URL at Ollama, llama.cpp, or vLLM and get real completions through the Bedrock API
• Real infrastructure — RDS spins up actual Postgres/MySQL containers, ElastiCache spins up real Redis/Valkey, Athena runs real SQL via DuckDB (full image only), ECS runs real Docker containers
• Tiny footprint — ~270MB image, ~30MB RAM at idle vs LocalStack's ~1GB image and ~500MB RAM
• Fast startup — under 2 seconds, HTTP/2 (h2c) supported
• MIT licensed — use it, fork it, contribute to it

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Python 3.8 or later
• pip / virtualenv for dependencies
• VS Code, PyCharm or Jupyter Notebook
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/ministackorg/ministack.git
cd ministack

# Option 1: PyPI (simplest)
pip install ministack
ministack
# Runs on http://localhost:4566 — use GATEWAY_PORT=XXXX to change

# Option 2: Docker Hub
docker run -p 4566:4566 ministackorg/ministack

# Option 2b: Docker Hub with real infrastructure (RDS, ECS, Lambda containers)
docker run -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock ministackorg/ministack

# Option 2c: Full image — Debian/glibc base with DuckDB (Athena), psycopg2, pymysql.
# Larger (~360 MB vs ~110 MB) but enables Athena and native PostgreSQL/MySQL drivers
# that don't ship musllinux wheels. Reports `edition: full` on /_ministack/health.
docker run -p 4566:4566 ministackorg/ministack:full

# Option 3: Clone and build
git clone https://github.com/ministackorg/ministack
cd ministack
docker compose up -d

# Verify (any option)
curl http://localhost:4566/_ministack/health

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add a CI/CD pipeline with GitHub Actions
• Deploy to a public test network or cloud free tier
• Add monitoring and cost alerts

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Why does this problem need a blockchain or cloud-native design?
2. Explain the smart contract / infrastructure components and how they interact.
3. How are gas costs or cloud costs kept under control?
4. How is the system secured (keys, IAM, access control)?
5. How would the solution scale to many more users?

9. Source Code & License

This project is developed by ministackorg and published on GitHub under the MIT License. Please follow the license terms and credit the original author when you use or modify this code.