# Set Up a Local AWS Environment with MiniStack

## Overview

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2F7tMYfQaYSJGK0rG6SVfB%2Fimage.png?alt=media&#x26;token=11d274cd-fd90-4ab3-942a-29e4ecf45bd1" alt=""><figcaption></figcaption></figure>

Running cloud infrastructure locally is now easier than ever with tools like MiniStack.

This shift became even more important recently, as LocalStack changed its model requiring accounts, authentication tokens, and introducing paid plans for full usage.

As a result, many developers are looking for simpler, fully local, and free alternatives.

[MiniStack](https://ministack.org/) lets you run AWS like services locally using real containers (Postgres, Redis, S3), making development faster, cheaper, and fully offline.

In this guide, we will use MiniStack to spin up a local AWS like environment and then use Stakpak to interact with it, configure it, and operate it.

{% hint style="warning" %}
**LocalStack moved core services behind a paid plan.** If you relied on LocalStack Community for local dev and CI/CD, [MiniStack](https://ministack.org/) is your free, MIT-licensed drop-in replacement. No sign up, no API key, no telemetry.
{% endhint %}

## Problem

Setting up and working with local cloud environments manually can still be painful:

* You need to configure services (databases, storage, networking)
* You have to remember CLI commands or SDK usage
* You need to debug issues across multiple containers
* You manually test if services are actually working
* You document setup steps for future use

Even with tools like MiniStack replacing LocalStack for many use cases, **operating local infrastructure is still manual work**.

Small mistakes like misconfigured services, missing environment variables, or broken connections can slow down development.

## How Stakpak Helps

Stakpak acts as an operator for your local infrastructure.

Instead of manually configuring and debugging everything, you can just tell Stakpak what you want, and it will:

* Understand your local MiniStack environment
* Detect running services (Postgres, Redis, S3, etc.)
* Configure and connect services together
* Run commands and fix issues automatically
* Validate that everything is working correctly
* Document what it did

Optionally, you can enable continuous checks later (with [autopilot](https://stakpak.gitbook.io/docs/how-it-works/autopilot "mention")), but for this guide we focus on setup and operations.

## Step-by-Step Guide

### Prerequisites

1. [install-stakpak](https://stakpak.gitbook.io/docs/get-started/install-stakpak "mention")
2. [MiniStack installed](https://ministack.org/) (or you can ask Stakpak to install it)
3. [Docker Installed](https://www.docker.com/get-started/) (or you can ask Stakpak to install it)

### Architecture

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FFt5PJxEolnhj7jd7UFmm%2FScreenshot%202026-04-03%20at%2013.58.02.png?alt=media&#x26;token=68a10794-7df4-4d76-a3d5-cf6c28a48563" alt=""><figcaption></figcaption></figure>

### Application

#### What the app does

A user uploads a CSV or JSON file.

* It lands in S3.
* An event sends a job to SQS.
* A Lambda reads the message.
* The Lambda parses the file and stores results in Postgres.
* It writes job state to Redis.

You can check the code source [here](https://github.com/noureldin-azzab/aws-local-file-processor)

Now we can start that we understand the app and the architecture, we can start deploying it

### Deployment

1. Open Stakpak and ask it to deploy your app locally. That's it!
2. It read the codebase and understood the architecture
3. Spun up MiniStack, Postgres, and Redis via Docker Compose
4. Bootstrapped AWS resources: S3 bucket, SQS queue, and Lambda
5. Connected SQS to Lambda so uploads trigger processing automatically

Not lets test it..

### Testing

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FyTnKOXIdSZSNYROSG3MJ%2Fimage.png?alt=media&#x26;token=a5a94b13-025c-4ebc-a0d7-474985d9ad71" alt=""><figcaption></figcaption></figure>

It's working 🥳

Here is what happened:&#x20;

* We uploaded sample.csv -> got back a job\_id
* Lambda fired within 5 seconds (SQS polling)
* Redis shows status: done, rows\_inserted: 5
* Postgres has all 5 rows parsed and stored

<figure><img src="https://2684022488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOFDKnFMEMmJjoclGx9Hr%2Fuploads%2FQ1tgcH8cn8IO1V0pRMTO%2Fimage.png?alt=media&#x26;token=86553426-a92d-4666-9357-f076ab0339a1" alt=""><figcaption></figcaption></figure>

## Extra Resources:

### Related Use Cases

* [detect-and-fix-missing-backups-for-a-postgresql-db-in-production](https://stakpak.gitbook.io/docs/tutorial/detect-and-fix-missing-backups-for-a-postgresql-db-in-production "mention")
* [deploy-your-own-openvpn-server-on-aws](https://stakpak.gitbook.io/docs/tutorial/deploy-your-own-openvpn-server-on-aws "mention")
* [containerize-next.js-application](https://stakpak.gitbook.io/docs/archive/containerize-next.js-application "mention")

and more...

### References

* [install-stakpak](https://stakpak.gitbook.io/docs/get-started/install-stakpak "mention")
* [configure-stakpak](https://stakpak.gitbook.io/docs/get-started/configure-stakpak "mention")
* [MiniStack Documentation](https://ministack.org/)