This project lets you run HTTP Lambda applications locally.

Why

AWS Lambda containers (like Bref containers) can run locally, but they must be invoked via the Runtime Interface Emulator API, which is not practical. Here's an example with curl:

# Run your Lambda function
docker run --rm -it -p 8080:8080 -v $(PWD):/var/task bref/php-80-fpm public/index.php

# Call your function
curl -XPOST "http://localhost:8080/2015-03-31/functions/function/invocations" -d '{ http event goes here }'

That sucks 👎

If you use Lambda + API Gateway, you probably just want to access your app via HTTP… like any other HTTP application. This project does that.

Usage

This project publishes a bref/local-api-gateway Docker image.

This image creates a local API Gateway (i.e. HTTP server) that forwards HTTP requests to your Lambda function running in Docker.

The only thing it needs is a TARGET environment variable that contains the endpoint of your Lambda function: <host>:<port> (the default port of Lambda RIE is 8080).

Example

Example of docker-compose.yml:

version: "3.5"

services:
  
    # This container runs API Gateway locally
    web:
        image: bref/local-api-gateway
        ports: ['8000:8000']
        environment:
            # <host>:<port> -> the host here is "php" because that's the name of the second container
            TARGET: 'php:8080'
            # Binds and listens for connections on the specified host and port. 0.0.0.0:8000 is the defailt configuration.
            # E.g. you can set LISTEN_PORT to 443 if you have issues to make https requests work.
            # LISTEN_ADDRESS: '0.0.0.0' 
            # LISTEN_PORT: 8000
            
    # Example of container running AWS Lambda locally
    php:
        image: bref/php-80-fpm
        # The command should contain the Lambda handler
        command: public/index.php
        volumes:
            - .:/var/task:ro

If you need to change the default listening port, you can set the LISTEN_PORT environment variable value to whatever port you wish to use.

Static assets

If you want a quick and easy way to serve static assets, mount your files in the bref/local-api-gateway container and set the DOCUMENT_ROOT env var to the root of the assets.

DOCUMENT_ROOT is relative to /var/task (the root of the app), so it can contain . if your assets are in the root of the app.

For example:

services:
    web:
        image: bref/local-api-gateway
        ports: ['8000:8000']
        volumes:
            - .:/var/task:ro
        environment:
            TARGET: 'php:8080'
            DOCUMENT_ROOT: public
            
    # ...

FAQ

This vs Serverless Offline

Serverless Offline doesn't work with Bref, and doesn't work great if you run your Lambda in containers.

This project will be useful to you if you are in that case, or simply if you don't use Serverless Framework.

However, if you use Serverless Framework with JS, Python or another supported language, Serverless Offline is probably a better choice.

Does this support API Gateway routes?

No. To discover routes (and how they map to Lambda functions), we would have to parse CloudFormation templates/serverless.yml/CDK files/Terraform files/Pulumi files/etc. That's too much work for now :)

This project is mostly useful for people running web frameworks (like Laravel, Symfony, etc.) in Lambda, and don't use API Gateway's routing.

Does this support API Gateway features?

No, this is a very simple HTTP server. It does not support API Gateway features like CORS, authorizers, etc.

How are parallel requests handled?

The Lambda RIE does not support parallel requests. This project handles them by "queueing" requests. If a request is already being processed, the next request will be queued and processed when the first request is done.

This works up to 10 requests in parallel by default. You can change this limit by setting the DEV_MAX_REQUESTS_IN_PARALLEL environment variable.