Getting Started with Localstack
Localstack is a containerized application which provides a means for emulating an AWS environment on a local development machine. It can be useful for iterating on development of Infrastructure-as-Code (IaC) scripts, such as Terraform, or to test deployments of serverless code, such as Lambda functions, without incurring the costs associated with a live AWS account.
Certain PDS applications, such as the Data Upload Manager (DUM), leverage Localstack to perform integration tests between client-side code and server-side Lambda functions, so this page is intended as a guide for getting up and running with the required Localstack applications needed to execute said integration test.
Localstack provides several means for installation, but for the purposes of this guide we will use pip. It is recommended to first create and activate a Python virtual environment to work out of:
python -m venv venv
source venv/bin/activate
Localstack can then be installed into this environment with the following:
python3 -m pip install localstack==<version>
Where <version> should be the latest available version, which at time of writing is 3.8.1
This will install the Localstack Command Line Interface (CLI). You can verify the installation by running the following:
$ localstack --version
3.8.1
To actually run Localstack, it is necessary to authorize the local CLI installation with an Authentication Token associated to a Localstack user account.
To begin, first create a user account here: https://app.localstack.cloud/sign-up
Note: When registering the account it is recommended you use an email address, rather than selecting the option for Github SSO. This is to ensure you are presented with the option to register for a "Hobbyist" account, which will allow you to proceed with the following instructions without incurring any recurring charges:
After creating and verifying the account, log in with your credentials here: https://app.localstack.cloud/sign-in
Once logged in, you should be brought to the Localstack webapp Dashboard:
Next, the license to be associated with the account must be selected and activated. This can be done from the Users and Licenses Menu (available from the Workspace tab on the left-side menu). For the purposes of these instructions, activating the "Hobby License" should be sufficient.
Once a license is active, navigate to the Auth Token page (under the Workspace tab on the left-side menu), or go to https://app.localstack.cloud/workspace/auth-token
Here you should be able to view and recreate (if necessary) the Auth Token associated to your account:
Copy the string value between the double-quotes, and use it with the following command to associate your Auth Key with your Localstack CLI installation:
localstack auth set-token <YOUR_AUTH_TOKEN>
Note: the Auth Token can also be exposed to the Localstack CLI via environment variable, in which case you would run the following instead:
export LOCALSTACK_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"
To start the Localstack instance within a container, run the following:
localstack start
You should see something similar to the following, including messages about a "Succesfully activated [..] license":
Note: The Localstack instance can also be started in "detached" mode, which allows it to run in the background:
localstack start -d
To halt the running Localstack instance:
localstack stop
There are two additional command-line utilities that are useful for working with Localstack, awslocal and tflocal. Each of these utilities act as wrappers around their corresponding command-line utilities (the aws CLI and terraform CLI, respectfully) which are pre-configured to communicate with an instance of Localstack, rather than a true AWS account.
Both of these utilities can also be installed via pip:
pip install awscli-local
pip install terraform-local
After installing, the awslocal and tflocal applications should be available from the command-line. The calling semantics of these applications should be exactly the same as the standard versions. For example, to interact with S3 on localstack via awslocal:
awslocal s3 ls
And to initialize Terraform for use with localstack:
tflocal init