AWS SAM CLI `local start-api` in docker-compose

README.md

Use AWS SAM CLI for Local Development

Among the options for local development of AWS Serverless Apps, the AWS SAM CLI is the latest to be supported by AWS.

Goal

We want to be able to use the AWS SAM CLI from a container so we can have a portable development and testing environment.

Problem 1 : There is no standard container released from Amazon for the AWS SAM CLI.

This is annoying, but is not insurmountable. Dockerfile provides an adequite example for how to build such a container.

Problem 2 : Argument --docker-volume-basedir does not work correctly.

The way sam local start-api works is by running a lambda container with the source code. When we containerize the AWS SAM CLI and mount our source code into it, we run into trouble with this process.

First, AWS SAM CLI will use docker to run the lambda container. We can either add docker to our AWS SAM CLI container, a Docker in Docker (DinD) solution, or mount the host docker into the container. DinD is bad practice, so we go the mount option by adding /var/run/docker.sock:/var/run/docker.sock.

Next, the lambda container will be invoked using a network call. By default, this will be localhost, which does not work from inside a container. Thankfully --container-host host.docker.internal solves this problem.

Lastly, the source files need to be mounted into the lambda container. We have no issue mounting the source files int our AWS SAM CLI container. When AWS SAM CLI constructs the mount it will use the file path from inside the AWS SAM CLI container. The problem is that the docker runtime is from the host system, and therefore can only mount files/directories that exist in the host system.

Solution 1: Use --docker-volume-basedir flag.

From the documentation, this value should tell AWS SAM CLI where the source code is on the system running docker. In this case, docker is on the local computer, so this value would need to be a valid path on the local computer.

However, this value is being ignored.

Solution 2: Use a working_dir in the container that matches the local filesystem.

When the directory in the AWS SAM CLI container with the source code matches the directory on your computer, then the mount will be created by coincidence.

We configure this with a combination of setting working_dir and mounting the source code using the same values. Thankfully docker-compose will create the directory paths in the container, otherwise we'd need to create the directory at runtime somehow.

For linux and mac systems, this is no problem since file paths will look the same, but there needs to be some translation on windows system.

Windows Example C:\Some\Windows\Path -> /c/Some/Windows/Path

Solution 3: Use Volume Mount Options

The lambda container expects the source code at /var/task so not all of these would work.

Use --volumes-from to copy mounts into the lambda container. The target directory is not controlable with this option, and the name of the source container may not be static.

Create a named volume and pass that around. This would probably be the best option.

docker-compose.yaml

version: "3.9"
services:
  sam:
    # build the docker file here, or docker build, and use image instead.
    build: .
    # Make the working directory of the container match the mount location of the source code.
    working_dir: $HOST_SOURCE_CODE_DIR
    volumes:
        # AWS CLI Credentials Mount
      - ~/.aws:/root/.aws
        # Mount Host Docker to avoid using Docker in Docker (DinD)
      - /var/run/docker.sock:/var/run/docker.sock
        # Mount Source code to same directory in the container
      - $HOST_SOURCE_CODE_DIR:$HOST_SOURCE_CODE_DIR
    ports:
      - "8080:3000"
    command: 
      - local
      - start-api
        # REQUIRED to allow AWS SAM container communicate with container running lambda code
      - --container-host
      - host.docker.internal
        # REQUIRED to allow host system to connect into this container's server
      - --host 
      - 0.0.0.0

Dockerfile

# Starting from offical aws-cli container.
FROM amazon/aws-cli:2.5.5

# Adding some unzip tool
RUN yum install -y unzip

# Download fixed version -> unzip -> run install script
RUN curl -L https://github.com/aws/aws-sam-cli/releases/download/v1.46.0/aws-sam-cli-linux-x86_64.zip -o /tmp/aws-sam.zip \
      && unzip /tmp/aws-sam.zip -d /tmp/aws-sam \
      && /tmp/aws-sam/install

# Decided to default entrypoint to call the sam command
# Could be changed to "" to include "sam" in runtime commands
ENTRYPOINT [ "sam" ]