Reading Time: 5 minutes

Have you ever thought of using AWS services offline i.e. without connecting to the internet? If your answer is No, don’t worry you are at the right place. Once you read this blog you will know how easily you can do this using LocalStack.

When we try experimenting with our cloud provider, it is necessary for us to have an account and most of the time we exhaust the free tier and it becomes very difficult for us to experiment something.

In this blog we are going to discuss about something called as LocalStack using which you can create a local AWS environment without connecting to the AWS console. Also, you will see how you can use it for your own projects.

What is LocalStack?

LocalStack is an open-source mock of the real AWS services. It provides a testing environment on our local machine with the same APIs as the real AWS services. We switch to using the real AWS services only in the integration environment and beyond.

Why use LocalStack?

The method of temporarily using dummy (or mock, fake, proxy) objects in place of actual ones is a popular way of running tests for applications with external dependencies. Most appropriately, these dummies are called Test Doubles. We can implement test doubles of our AWS services with LocalStack.

LocalStack supports:

• running our applications without connecting to AWS.
• avoiding the complexity of AWS configuration and focus on development.
• running tests in our CI/CD pipeline.
• configuring and testing error scenarios.

Services Supported by LocalStack

LocalStack spins up the following core Cloud APIs on your local machine.

• API Gateway
• CloudFormation
• CloudWatch
• CloudWatch Logs
• DynamoDB
• DynamoDB Streams
• Elasticsearch Service
• EventBridge (CloudWatch Events)
• Firehose
• Kinesis
• Lambda
• Redshift
• Route53
• SecretsManager
• StepFunctions

Note: LocalStack supporting only AWS cloud stack.

Running LocalStack

LocalStack usually runs inside a Docker container, but we can also run it as a Python application instead.

Running LocalStack as a Python application

First we need to install the LocalStack package using pip:

pip install localstack

Once the localstack package is installed, we will start localstack using the below command:

localstack start

Running LocalStack as a Docker container

LocalStack can be started within a single docker container. It has quite some possibilities to change it’s configuration. By setting the right environment variables you can configure what service you want to enable. The single container will be the host of the LocalStack application, to reach certain services you need to address a single edge service of LocalStack that is exposed on port 4566.

Before running LocalStack as a Docker container make sure you have installed AWS CLI, docker and docker-compose in your system.

We can run LocalStack directly as a Docker image either by using the docker run command or with docker-compose. We will use docker-compose. For that, we will use the base version of docker-compose.yml file and customize it as per our requirements. You can also run it without changes if you prefer to use the default configuration.

Example docker-compose.yml:

version: "3.8"

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME-localstack_main}"
    image: localstack/localstack
    network_mode: bridge
    ports:
      - "4566:4566"
      - "4571:4571"
      - "${PORT_WEB_UI-of8080}:${PORT_WEB_UI-8080}"
    environment:
      - SERVICES= kinsesis,dynamodb
      - 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
      - HOST_TMP_FOLDER=${TMPDIR}
    volumes:
      - "${TMPDIR:-/tmp/localstack}:/tmp/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

In the above docker-compose.yml file, we are configuring LocalStack to spin up a limited set of services by setting a comma-separated list of service names as value for the environment variable SERVICES: For the demo purpose we are using only two AWS Services namely:

1. kinsesis
2. dynamodb

So we have set the environment variable SERVICES to the name of the services we want to use (kinsesis and dynamodb)

Once you configured the above docker-compose.yml file, run the below command to start localstack in a docker container

docker-compose up

Here are the logs that you’ll see once we run the above command.

To check the status of the container where your localstack service is running, run the below command:

docker ps

Connecting to LocalStack

To connect to your running LocalStack container from your localhost you need to expose the ports to your host machine. Once everything is set up you can connect to LocalStack like you would connect to AWS using your localhost as aws-endpoint.

Since LocalStack is built to imitate AWS locally you’re able to use the AWS CLI against the LocalStack docker container.

We start by creating a fake profile in the AWS CLI so that we can later use the AWS CLI for invoking the services provided by LocalStack. For this, we’ll run the below command:

aws configure --profile mockService

This creates a fake profile named mockService (we can call it whatever we want) and will prompt for the AWS Access Key, Secret Access Key, and an AWS region. You can provide any dummy value for the credentials and a valid region name like us-east-1, but don’t leave any of the values blank.

Unlike AWS, LocalStack does not validate these credentials but complains if no profile is set. So far, it’s just like any other AWS profile which we will use to work with LocalStack.

Once your profile is created, proceed to execute the AWS CLI commands by passing an additional parameter for overriding the endpoint URL:

aws --endpoint-url http://localhost:4566 kinesis list-streams

Executing this command will send the requests to the URL of LocalStack specified as the value of the endpoint URL command line parameter (localhost on port 4566) instead of the real AWS endpoint and lists the available kinesis data streams(In our case the list wil be empty as we have not created any data streams).

In the same way, we can run CLI commands for all the supported services and spun up by our instance of LocalStack.

Access the Services

The default behaviour of LocalStack is to spin up all the supported services with each of them listening on port 4566. So you can access them by typing the following url (http://localhost:4566) on your browser.

Note: The default port 4566 can be overridden by setting the environment variable EDGE_PORT.

Conclusion

So we have seen how to use LocalStack to create a local AWS environment just by running its image as a docker container. This will allow us to access the AWS services locally.

Hope you find this content useful and will have more fun while working with AWS services during development and lead to higher productivity, shorter development cycles, and lower AWS cloud bills.

To learn more about LocalStack and the services it supports, check out this GitHub repository of LocalStack.

For more such blogs, visit https://blog.knoldus.com