• Stars
    star
    508
  • Rank 84,705 (Top 2 %)
  • Language
    JavaScript
  • Created over 5 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

⚑ Serverless plugin for running against LocalStack

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:

  • LocalStack

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
  stages:
    local:
      ...

Configuration via environment variables

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)

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

  • 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 repo
  • LAMBDA_REMOTE_DOCKER: Whether to assume that we're running Lambda containers against a remote Docker daemon (default false) - see LocalStack repo
  • BUCKET_MARKER_LOCAL: Magic S3 bucket name for Lambda mount and Hot Reloading.

Only enable serverless-localstack for the listed stages

  • 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

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

  • v1.1.1: Fix layer deployment if mountCode is enabled by always packaging and deploying
  • v1.1.0: Fix SSM environment variables resolving issues with serverless v3, change default for BUCKET_MARKER_LOCAL to hot-reload
  • v1.0.6: Add BUCKET_MARKER_LOCAL configuration for customizing S3 bucket for lambda mount and Hot Reloading.
  • v1.0.5: Fix S3 Bucket LocationConstraint issue when the provider region is us-east-1
  • v1.0.4: Fix IPv4 fallback check to prevent IPv6 connection issue with localhost on macOS
  • v1.0.3: Set S3 Path addressing for internal Serverless Custom Resources - allow configuring S3 Events Notification for functions
  • v1.0.2: Add check to prevent IPv6 connection issue with localhost on MacOS
  • v1.0.1: Add support for Serverless projects with esbuild source config; enable config via environment variables
  • v1.0.0: Allow specifying path for mountCode, to point to a relative Lambda mount path
  • v0.4.36: Add patch to avoid "TypeError" in AwsDeploy plugin on Serverless v3.4.0+
  • v0.4.35: Add config option to connect to additional Docker networks
  • v0.4.33: Fix parsing StepFunctions endpoint if the endpointInfo isn't defined
  • v0.4.32: Add endpoint to AWS credentials for compatibility with serverless-domain-manager plugin
  • v0.4.31: Fix format of API GW endpoints printed in stack output
  • v0.4.30: Fix plugin for use with Serverless version 2.30+
  • v0.4.29: Add missing service endpoints to config
  • v0.4.28: Fix plugin activation for variable refs in profile names
  • v0.4.27: Fix loading of endpoints file with variable references to be resolved
  • v0.4.26: Fix resolution of template variables during plugin initialization
  • v0.4.25: Use single edge port instead of deprecated service-specific ports
  • v0.4.24: Fix resolving of stage/profiles via variable expansion
  • v0.4.23: Fix config loading to enable file imports; fix output of API endpoints if plugin is not activated; enable SSM and CF output refs by performing early plugin loading
  • v0.4.21: Fix integration with serverless-plugin-typescript when mountCode is enabled
  • v0.4.20: Use LAMBDA_EXECUTOR/LAMBDA_REMOTE_DOCKER configurations from environment
  • v0.4.19: Fix populating local test credentials in AWS provider
  • v0.4.18: Fix output of API Gateway endpoints; add port mappings; fix config init code
  • v0.4.17: Enable configuration of $START_WEB
  • v0.4.16: Add option for running Docker as sudo; add fix for downloadPackageArtifacts
  • v0.4.15: Enable plugin on aws:common:validate events
  • v0.4.14: Initialize LocalStack using hooks for each "before:" event
  • v0.4.13: Add endpoint for SSM; patch serverless-secrets plugin; allow customizing $DOCKER_FLAGS
  • v0.4.12: Fix Lambda packaging for mountCode:false
  • 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_CWD configuration 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

More Repositories

1

localstack

πŸ’» A fully functional local AWS cloud stack. Develop and test your cloud & Serverless apps offline
Python
51,683
star
2

awscli-local

πŸ’² "awslocal" - Thin wrapper around the "aws" command line interface for use with LocalStack
Python
1,012
star
3

aws-cdk-local

Thin wrapper script for using the AWS CDK CLI with LocalStack
JavaScript
243
star
4

localstack-python-client

🐍 A lightweight Python client for LocalStack
Python
171
star
5

terraform-local

Terraform CLI wrapper to deploy your Terraform applications directly to LocalStack
Python
165
star
6

localstack-pro-samples

Sample projects to demonstrate advanced LocalStack features
Makefile
153
star
7

localstack-java-utils

β˜• Java utilities and JUnit integration for LocalStack
Java
77
star
8

plux

A dynamic code loading framework for building pluggable Python distributions
Python
69
star
9

pulumi-local

Thin wrapper script to use Pulumi with LocalStack
Python
68
star
10

localstack-terraform-samples

Repository with terraform samples for LocalStack
HCL
66
star
11

localstack-demo

Simple demo application deployed using LocalStack
Makefile
57
star
12

helm-charts

Helm Charts for LocalStack
Smarty
49
star
13

docs

The LocalStack documentation πŸ“–
HTML
48
star
14

aws-sam-cli-local

Simple wrapper around AWS SAM CLI for use with LocalStack
Python
48
star
15

localstack-docker-extension

Simple Docker Extension to control and manage your LocalStack instance
TypeScript
39
star
16

localstack-extensions

🧩 Extend and customize LocalStack with LocalStack Extensions (beta)
Python
31
star
17

localstack-terraform-test

Utilities to run Terraform tests against LocalStack
Python
24
star
18

chalice-local

Small wrapper script to use AWS Chalice with LocalStack
Python
21
star
19

verdin

A Tinybird SDK for Python 🐦
Python
20
star
20

awesome-localstack

A curated list of LocalStack integrations, tools, frameworks, and platforms.
20
star
21

setup-localstack

Sets up LocalStack CLI in your GitHub Actions workflow ☁️
19
star
22

amplify-js-local

Simple wrapper script to allow using the Amplify JS SDK with LocalStack
JavaScript
19
star
23

cockpit

LocalStack Cockpit Desktop application
18
star
24

serverless-python-rest-api-with-dynamodb

Serverless CRUD service exposing a REST HTTP interface integrated with LocalStack
Python
16
star
25

localstack-on-k8s

Sample repository that illustrates running LocalStack on Kubernetes
Python
14
star
26

localstack-desktop

The official LocalStack Desktop Application
14
star
27

localstack-workshop

Repository with code samples for the LocalStack workshop
JavaScript
13
star
28

localstack.github.io

LocalStack website
HTML
12
star
29

localstack-vscode-extension

LocalStack VSCode Extension: Deploy Lambda functions to LocalStack
TypeScript
12
star
30

azure-cli-local

[unmaintained] Simple wrapper script to use Azure CLI with LocalStack
Python
11
star
31

localstack-cli

The LocalStack CLI packaged using pyinstaller
Makefile
10
star
32

presentations

Presentations, talks, and demos about LocalStack
HCL
10
star
33

localstack-github-actions-login

GitHub Action to log-in into your LocalStack account on your GitHub Actions runners
JavaScript
9
star
34

rolo

A Python framework for building HTTP-based server applications
Python
9
star
35

localstack-aws-sdk-examples

Test repo with sample apps & tests for various different languages/SDKs using LocalStack
Java
8
star
36

cloud-pods

Sample repository illustrating Cloud Pods for LocalStack
JavaScript
7
star
37

localstack-artifacts

Miscellaneous build artifacts for the LocalStack platform
Java
7
star
38

serverless-streaming-data-pipeline

A serverless streaming data pipeline running on LocalStack
Python
7
star
39

serverless-api-ecs-apigateway-sample

Serverless Container-based APIs with Amazon ECS and Amazon API Gateway deployed using LocalStack
HCL
6
star
40

localstack-moto-test-coverage

Repo to run moto integration tests against LocalStack for moto-fallback coverage
Python
6
star
41

ci-plugin-circleci

CircleCI Plugin (Orb) for easy configuration of LocalStack CI builds
Shell
5
star
42

localstack-plugin-loader

The dynamic code loading framework used in LocalStack
Python
5
star
43

architect-local

Architect CLI (arc.codes) for use with LocalStack
JavaScript
5
star
44

mnist-sagemaker

Demo to run the MNIST handwritten digit model on a locally running SageMaker endpoint
JavaScript
5
star
45

awslamba-go-runtime

Custom Golang runtime for the execution of AWS Lambdas
Go
5
star
46

.github

Community health files for the @localstack organization
5
star
47

localstack-pulumi-samples

Sample Pulumi projects to demonstrate LocalStack features
Python
4
star
48

localstack-stripe

Use the Stripe API in LocalStack
Python
4
star
49

local-surf

πŸ„ LocalSurf - a browser plugin to redirect AWS service calls to LocalStack
JavaScript
4
star
50

amplify-localstack

Amplify Plugin to deploy resources into Localstack
JavaScript
4
star
51

appsync-utils

Implementation of AppSync JavaScript utilities
JavaScript
4
star
52

tinybird-workflow-push

Push Github Workflow data to tinybird
TypeScript
4
star
53

devops-barcelona-2022

LocalStack @ DevOps Bareclona 2022
Python
3
star
54

branding

Repository with various LocalStack branding assets
3
star
55

localstack-docker-debug

Python
3
star
56

homebrew-tap

Ruby
3
star
57

pre-commit-hooks

Pre commit hooks for LocalStack repositories
Python
3
star
58

localstack-snapshot

Extracted snapshot testing library for LocalStack
Python
3
star
59

serverless-image-resizer

Serverless Image Resizer demo app for LocalStack
Python
2
star
60

localstack-python-utils

Localstack utility for tests
Python
2
star
61

cloud-pod-badge

2
star
62

appsync-graphql-api-sample

Proxy data from different resources such as DynamoDB tables & RDS databases using AppSync GraphQL APIs deployed using Serverless Framework on LocalStack
Shell
2
star
63

localstack-dev-spaces

Sample repo for running LocalStack in Redhat Openshift Dev Spaces
Dockerfile
2
star
64

aws-java-sdk-v2-trust-certs-patch

A small java agent to patch the AWS Java SDK v2 to disable certificate name validation.
Java
1
star
65

localstack-blog.github.io

LocalStack blog
HTML
1
star
66

loan-broker-stepfunctions-lambda-app

TypeScript
1
star
67

shipyard-localstack-flask

a starter Flask project, integrated with Localstack and Shipyard
Python
1
star
68

troubleshooting-issues

Repository of samples to reproduce localstack issues
Python
1
star
69

meta

Tooling to manage repos in the localstack org
1
star
70

reinvent-challenge

Repository for re:Invent "scavenger hunt" using LocalStack
Shell
1
star
71

azure-functions-local

Small wrapper script to use Azure Functions core tools with LocalStack
1
star