Serverless plugin for LocalStack - a fully functional local AWS cloud stack. Develop and test your cloud & Serverless apps offline!
user
LocalStack
Serverless Plugin to support running against Localstack.
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.
Pre-requisites:
The easiest way to get started is to install via npm.
npm install -g serverless
npm install --save-dev serverless-localstack
There are two ways to configure the plugin, via a JSON file or via serverless.yml
.
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.
A host
or individual endpoints must be configured or this plugin will be deactivated.
Please refer to the example configuration template below. (Please note that most configurations in the sample are optional and need not be specified.)
service: myService
plugins:
- serverless-localstack
custom:
localstack:
stages:
# list of stages for which the plugin should be enabled
- local
host: http://localhost # optional - LocalStack host to connect to
edgePort: 4566 # optional - LocalStack edge port to connect to
autostart: true # optional - Start LocalStack in Docker on Serverless deploy
lambda:
# Enable this flag to improve performance
mountCode: True
docker:
# Enable this flag to run "docker ..." commands as sudo
sudo: False
stages:
local:
...
Note the stages
attribute in the config above. The serverless-localstack
plugin gets activated if either:
1. the serverless stage (explicitly defined or default stage "dev") is included in the stages
config; or
2. serverless is invoked without a --stage
flag (default stage "dev") and no stages
config is provided
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 run
requires us
to specify a local_dir
relative to the Windows host file system that is mounted
into the VM (e.g., "c:/users/guest/..."
).LAMBDA_EXECUTOR
: Executor type to use for running Lambda functions (default docker
) -
see LocalStack repoLAMBDA_REMOTE_DOCKER
: Whether to assume that we're running Lambda containers against
a remote Docker daemon (default false
) - see LocalStack reposerverless deploy --stage local
would deploy to LocalStack.serverless deploy --stage production
would 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.
git clone https://github.com/localstack/serverless-localstack
cd /path/to/serverless-localstack
npm link
cd myproject
npm link serverless-localstack
An optional debug flag is supported via serverless.yml
that will enable additional debug logs.
custom:
localstack:
debug: true
serverless-plugin-typescript
when mountCode
is enabledLAMBDA_EXECUTOR
/LAMBDA_REMOTE_DOCKER
configurations from environment$START_WEB
mountCode:false
LAMBDA_MOUNT_CWD
configuration for customizing Lambda mount dirLatest commit b2f54ec on Sep 24, 2017