LocalStack Serverless Plugin
This plugin allows Serverless applications to be deployed and tested on your local machine. Any requests to AWS to be redirected to a running LocalStack instance.
The easiest way to get started is to install via npm.
npm install -g serverless npm install --save-dev serverless-localstack
Installation (without npm)
If you'd like to install serverless-localstack via source:
Clone the repository
git clone https://github.com/localstack/serverless-localstack cd serverless-localstack npm link
Install the plugin
npm link to reference the plugin
cd project-path/ npm link serverless-localstack
There are two ways to configure the plugin, via a JSON file or via
There are two supported methods for configuring the endpoints, globally via the
host property, or individually. These properties may be mixed, allowing for
global override support while also override specific endpoints.
host or individual endpoints must be configured or this plugin will be deactivated.
Configuration via serverless.yml
service: myService plugins: - serverless-localstack custom: localstack: host: http://localhost stages: # list of stages for which the plugin should be enabled - local autostart: true # optional - start LocalStack in Docker on Serverless deploy endpoints: # This section is optional - can be used for customizing the target endpoints S3: http://localhost:4572 DynamoDB: http://localhost:4570 CloudFormation: http://localhost:4581 Elasticsearch: http://localhost:4571 ES: http://localhost:4578 SNS: http://localhost:4575 SQS: http://localhost:4576 Lambda: http://localhost:4574 Kinesis: http://localhost:4568 lambda: # Enable this flag to improve performance mountCode: True stages: local: ...
Activating the plugin for certain stages
stages attribute in the config above. The
serverless-localstack plugin gets activated if either:
- the serverless stage (explicitly defined or default stage "dev") is included in the
- serverless is invoked without a
--stageflag (default stage "dev") and no
stagesconfig is provided
Mounting Lambda code for better performance
Note that the
localstack.lambda.mountCode flag above will mount the local directory
into the Docker container that runs the Lambda code in LocalStack. If you remove this
flag, your Lambda code is deployed in the traditional way which is more in line with
how things work in AWS, but also comes with a performance penalty: packaging the code,
uploading it to the local S3 service, downloading it in the local Lambda API, extracting
it, and finally copying/mounting it into a Docker container to run the Lambda.
LAMBDA_MOUNT_CWD: Allow users to define a custom working directory for Lambda mounts. For example, when deploying a Serverless app in a Linux VM (that runs Docker) on a Windows host where the
-v <local_dir>:<cont_dir>flag to
docker runrequires us to specify a
local_dirrelative to the Windows host file system that is mounted into the VM (e.g.,
Configuring endpoints via JSON
service: myService plugins: - serverless-localstack custom: localstack: endpointFile: path/to/file.json
Only enable serverless-localstack for the listed stages
serverless deploy --stage localwould deploy to LocalStack.
serverless deploy --stage productionwould deploy to aws.
service: myService plugins: - serverless-localstack custom: localstack: stages: - local - dev endpointFile: path/to/file.json
For full documentation, please refer to https://github.com/localstack/localstack
Setting up a development environment is easy using Serverless' plugin framework.
Clone the Repo
git clone https://github.com/localstack/serverless-localstack
Setup your project
cd /path/to/serverless-localstack npm link cd myproject npm link serverless-localstack
Optional Debug Flag
An optional debug flag is supported via
serverless.yml that will enable additional debug logs.
custom: localstack: debug: true
- v0.4.12: Fix Lambda packaging for
- v0.4.11: Add polling loop for starting LocalStack in Docker
- v0.4.8: Auto-create deployment bucket; autostart LocalStack in Docker
- v0.4.7: Set S3 path addressing; add eslint to CI config
- v0.4.6: Fix port mapping for service endpoints
- v0.4.5: Fix config to activate or deactivate the plugin for certain stages
- v0.4.4: Add
LAMBDA_MOUNT_CWDconfiguration for customizing Lambda mount dir
- v0.4.3: Support local mounting of Lambda code to improve performance
- v0.4.0: Add support for local STS