Local AWS environment with LocalStack
Tags: localstack, aws
Published: 2019-05-19 12:59:05

---
title: Local AWS environment with LocalStack
published: true
description: Tutorial on how to setup a local AWS environment with LocalStack
tags: Localstack, aws
---

# Useful links
- [LocalStack git repository](https://github.com/localstack/localstack)
- [Aws available services](https://docs.aws.amazon.com/cli/latest/reference/#available-services)
- [Aws docs](https://docs.aws.amazon.com/cli/latest/userguide/aws-cli.pdf)

# LocalStack
The definition used in their git repo is clear enough so let's just use it here:

> LocalStack provides an easy-to-use test/mocking framework for developing Cloud applications

# Setup

This tutorial uses a docker-image in order to setup Localstack, so you should have Docker and Docker-compose installed to move forward here.

Create a `docker-compose.localstack.yml` at the root of the project with the following content (which can be found [here](https://github.com/localstack/localstack#running-in-docker)):
```dockerfile
version: '2.1'
services:
...
  localstack:
    image: localstack/localstack
    ports:
      - "4567-4584:4567-4584"
      - "${PORT_WEB_UI-8080}:${PORT_WEB_UI-8080}"
    environment:
      - SERVICES=${SERVICES- }
      - DEBUG=${DEBUG- }
      - DATA_DIR=${DATA_DIR- }
      - PORT_WEB_UI=${PORT_WEB_UI- }
      - LAMBDA_EXECUTOR=${LAMBDA_EXECUTOR- }
      - KINESIS_ERROR_PROBABILITY=${KINESIS_ERROR_PROBABILITY- }
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - "${TMPDIR:-/tmp/localstack}:/tmp/localstack"
```

Spin up a Localstack docker container with `s3` and `dynamodb`

For MacOS users (in case your $TMPDIR contains a symbolic link that cannot be mounted by Docker):
```sh
TMPDIR=/private$TMPDIR PORT_WEB_UI=9000 SERVICES=s3,dynamodb docker-compose -f docker-compose.localstack.yml up
```

Other users:
```sh
PORT_WEB_UI=9000 SERVICES=s3,dynamodb docker-compose -f docker-compose.localstack.yml up
```
:information_source: Quick ref:
**-f** - Specify an alternate compose file (default: docker-compose.yml)
**-d** - Run as daemon process (in background)

> :warning: The names of the services to be used must follow the official aws services naming convention which can be found in [aws available services](https://docs.aws.amazon.com/cli/latest/reference/#available-services)

Useful `docker` commands:
- `docker ps`: List running containers
- `docker logs <container-name>`: Output logs container

---

## Api calls to LocalStack

Visit http://localhost:9000 to make sure your local AWS is working. You're expected to see an empty dashboard.

Lets make some api calls to our local aws to check if we can start interacting with it.

> :mag_right: Here is a complete user guide on [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/aws-cli.pdf) (Go to S3 section)

```bash
# Create a bucket
aws-vault exec scd-stg -- aws s3 mb s3://my-custom-bucket --endpoint-url http://localhost:4572
```
Expected output or similar: `make_bucket: my-custom-bucket`

```bash
# List buckets
aws-vault exec scd-stg -- aws s3 ls --endpoint-url http://localhost:4572
```
Expected output or similar: `2006-02-03 14:45:09 my-custom-bucket`

---

Let me know if you had any issues in the comments below, or leave a reaction if everything worked as expected.