search

localstack / serverless-localstack

⚡ Serverless plugin for running against LocalStack
511 stars 82 forks source link
aws aws-lambda serverless serverless-framework

readme

Build Status

LocalStack Serverless Plugin

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:

Installation

The easiest way to get started is to install via npm.

npm install -g serverless
npm install --save-dev serverless-localstack

Configuring

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.

Configuration via serverless.yml

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
      compose_file: /home/localstack_compose.yml # optional to use docker compose instead of docker or localstack cli
  stages:
    local:
      ...

Configuration via environment variables

The following environment variables can be configured (taking precedence over the values in serverless.yml):

Activating the plugin for certain stages

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

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. 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

A note on using webpack

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

Environment Configurations

Only enable serverless-localstack for the listed stages

service: myService

plugins:
  - serverless-localstack

custom:
  localstack:
    stages:
      - local
      - dev
    endpointFile: path/to/file.json

LocalStack

For full documentation, please refer to https://github.com/localstack/localstack

Contributing

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

Change Log