Learn LocalStack - Setup & First Run

#Introduction

In episode 2 we tore apart the LocalStack architecture: a single gateway at http://localhost:4566, provider-based design, and the difference between stateful emulation and mocking. Now it's time for theory to become practice — we'll run the emulator for the first time and verify that everything actually works.

This episode is the most decisive moment in the series: if you can get LocalStack running and talk to it through awslocal, then the following episodes (S3, DynamoDB, Lambda, and more) will feel easy. Conversely, if the setup fails here, none of the later material can be tried out.

#Preparation Before Starting

Make sure three things are in place before starting LocalStack:

The Docker daemon is running — check with docker info or docker ps.
The CLI is installed — localstack --version should display a version, e.g. 2026.7.x.
Port 4566 is free — make sure no other process is using it.

Warning

Port 4566 conflicts are one of the most common causes of failure. If another application is using that port, LocalStack fails to bind its gateway. Identify it with lsof -i :4566 or netstat -tulpn before starting.

#Running with localstack start

The fastest way is to use the CLI. Make sure Docker is running, then run:

Memulai LocalStack dalam mode Docker

localstack start

This command pulls the localstack/localstack:latest image (if not already present), runs a container named localstack-main, then waits until it's ready. Once it's running, you'll see the Ready. message at the end of the log. Check from the Docker side:

Melihat container LocalStack

docker ps --filter name=localstack-main

Note

localstack start runs the emulator in the background as a Docker container. You can follow the log output at any time with localstack logs.

#Running with Docker Compose

For teams and CI, a more reproducible way is to define the environment through docker-compose.yml. This makes the whole configuration a versioned artifact in Git.

docker-compose.yml

services:
  localstack:
    image: localstack/localstack:latest
    container_name: localstack-main
    ports:
      - "4566:4566"
      - "4510-4559:4510-4559"
    environment:
      - PERSISTENCE=1
      - DEBUG=1
    volumes:
      - "./.localstack:/var/lib/localstack"

Run it with:

Menjalankan dengan Docker Compose

docker compose up -d
docker compose ps

Tip

Mounting the volume ./.localstack:/var/lib/localstack stores emulator data to local disk. Useful when PERSISTENCE=1 so state isn't lost when the container restarts — we'll cover this in detail in episodes 4 and 12.

#Waiting Until It's Running

The emulator needs a few seconds until all services are active. Don't issue commands before it's ready — LocalStack provides a health endpoint at /_localstack/health that responds with per-service status. The following script waits until the emulator is ready to serve requests:

Menunggu LocalStack siap

for i in $(seq 1 30); do
  curl -sf http://localhost:4566/_localstack/health >/dev/null && break
  echo "Menunggu LocalStack siap..."
  sleep 2
done

#Basic Verification

Once it's running, verify with three key commands:

localstack status
localstack services

What each command does:

Command	Purpose
`localstack status`	Shows the container status, image version, and whether the emulator is `running`
`localstack services`	Lists all available and active AWS services
`awslocal sts get-caller-identity`	Verifies authentication; returns an identity with the fake `test`/`test` credentials

If everything works, awslocal sts get-caller-identity returns JSON containing an Account and Arn with the default test credentials. That means the emulator accepts authentication and is ready to use.

Warning

If localstack status doesn't show running, check the two most common things: whether port 4566 is being used by another process, and whether the Docker daemon is running. Use localstack logs to see the actual error.

#Closing

Run LocalStack with localstack start (Docker mode) or docker compose up -d with the localstack/localstack service.
Wait until the status is running — it can be monitored via the /_localstack/health endpoint.
Verify with localstack status, localstack services, and awslocal sts get-caller-identity.

Your emulator is now alive. In the next episode, episode 4, we learn how to manage its lifecycle professionally: localstack start, stop, restart, status, logs, config, plus important environment variables like PERSISTENCE, DEBUG, and SERVICES. Keep the emulator running for the upcoming material!