serverless-localstack
Advanced tools
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
The plugin can be configured via serverless.yml, or alternatively via environment variables.
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
networks: #optional - attaches the list of networks to the localstack docker container after startup
- host
- overlay
- my_custom_network
lambda:
# Enable this flag to improve performance
mountCode: true # specify either "true", or a relative path to the root Lambda mount path
docker:
# Enable this flag to run "docker ..." commands as sudo
sudo: False
stages:
local:
...
The following environment variables can be configured (taking precedence over the values in serverless.yml):
EDGE_PORT: LocalStack edge port to connect to (default: 4566)LOCALSTACK_HOSTNAME: LocalStack host name to connect to (default: localhost)Note the stages attribute in the config above. The serverless-localstack plugin gets activated if either:
stages config; or--stage flag (default stage "dev") and no stages config is providedNote that the localstack.lambda.mountCode flag above will mount the local directory into
the Docker container that runs the Lambda code in LocalStack. You can either specify the boolean
value true (to mount the project root folder), or a relative path to the root Lambda mount path
within your project (e.g., ./functions).
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. Mounting code
from multiple projects is not supported with simple configuration, and you must use the
autostart feature, as your code will be mounted in docker at start up. If you do need to
mount code from multiple serverless projects, manually launch
localstack with volumes specified. For example:
localstack start --docker -d \
-v /path/to/project-a:/path/to/project-a \
-v /path/to/project-b:/path/to/project-b
If you use either serverless-webpack, serverless-plugin-typescript, or serverless-esbuild, serverless-localstack
will detect it and modify the mount paths to point to your output directory. You will need to invoke
the build command in order for the mounted code to be updated. (eg: serverless webpack). There is no
--watch support for this out of the box, but could be accomplished using nodemon:
npm i --save-dev nodemon
Webpack example's package.json:
"scripts": {
"build": "serverless webpack --stage local",
"deploy": "serverless deploy --stage local",
"watch": "nodemon -w src -e '.*' -x 'npm run build'",
"start": "npm run deploy && npm run watch"
},
npm run start
serverless-webpack is supported, with code mounting. However, there are some assumptions
and configuration requirements. First, your output directory must be .webpack. Second, you must retain
your output directory contents. You can do this by modifying the custom > webpack portion of your
serverless configuration file.
custom:
webpack:
webpackConfig: webpack.config.js
includeModules: true
keepOutputDirectory: true
localstack:
stages:
- local
lambda:
mountCode: true
autostart: true
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 repoBUCKET_MARKER_LOCAL: Magic S3 bucket name for Lambda mount and Hot Reloading.serverless 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
BUCKET_MARKER_LOCAL configuration for customizing S3 bucket for lambda mount and Hot Reloading.us-east-1localhost on macOSlocalhost on MacOSserverless-plugin-typescript when mountCode is enabledLAMBDA_EXECUTOR/LAMBDA_REMOTE_DOCKER configurations from environment$START_WEBmountCode:falseLAMBDA_MOUNT_CWD configuration for customizing Lambda mount dirFAQs
Connect Serverless to LocalStack!
The npm package serverless-localstack receives a total of 40,561 weekly downloads. As such, serverless-localstack popularity was classified as popular.
We found that serverless-localstack demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.