Building applications

To build your serverless application, use the sam build command. This command also gathers the build artifacts of your application's dependencies and places them in the proper format and location for next steps, such as locally testing, packaging, and deploying.

You specify your application's dependencies in a manifest file, such as requirements.txt (Python) or package.json (Node.js), or by using the Layers property of a function resource. The Layers property contains a list of AWS Lambda layer resources that the Lambda function depends on.

The format of your application's build artifacts depends on each function's PackageType property. The options for this property are:

• Zip – A .zip file archive, which contains your application code and its dependencies. If you package your code as a .zip file archive, you must specify a Lambda runtime for your function.

• Image – A container image, which includes the base operating system, runtime, and extensions, in addition to your application code and its dependencies.

For more information about Lambda package types, see Lambda deployment packages in the AWS Lambda Developer Guide.

Building a .zip file archive

To build your serverless application as a .zip file archive, declare PackageType: Zip for your serverless function.

AWS SAM builds your application for the architecture that you specify. If you don't specify an architecture, AWS SAM uses x86_64 by default.

If your Lambda function depends on packages that have natively compiled programs, use the --use-container flag. This flag locally compiles your functions in a Docker container that behaves like a Lambda environment, so they're in the right format when you deploy them to the AWS Cloud.

When you use the --use-container option, by default AWS SAM pulls the container image from Amazon ECR Public. If you would like to pull a container image from another repository, for example DockerHub, you can use the --build-image option and provide the URI of an alternate container image. Following are two example commands for building applications using container images from the DockerHub repository:

# Build a Node.js 12 application using a container image pulled from DockerHub
sam build --use-container --build-image amazon/aws-sam-cli-build-image-nodejs12.x

# Build a function resource using the Python 3.8 container image pulled from DockerHub
sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.8 

For a list of URIs you can use with --build-image, see Image repositories which contains DockerHub URIs for a number of supported runtimes.

For additional examples of building a .zip file archive application, see the Examples section later in this topic.

Building a container image

To build your serverless application as a container image, declare PackageType: Image for your serverless function. You must also declare the Metadata resource attribute with the following entries:

Dockerfile

The name of the Dockerfile associated with the Lambda function.

DockerContext

The location of the Dockerfile.

DockerTag

(Optional) A tag to apply to the built image.

DockerBuildArgs

Build arguments for the build.

The following is an example Metadata resource attribute section:

    Metadata:
      Dockerfile: Dockerfile
      DockerContext: ./hello_world
      DockerTag: v1

To download a sample application that's configured with the Image package type, see Step 1: Download a sample AWS SAM application in Tutorial: Deploying a Hello World application. At the prompt asking which package type you want to install, choose Image.

Note

If you specify a multi-architecture base image in your Dockerfile, AWS SAM builds your container image for your host machine's architecture. To build for a different architecture, specify a base image that uses the specific target architecture.

Container environment variable file

To provide a JSON file that contains environment variables for the build container, use the --container-env-var-file argument with the sam build command. You can provide a single environment variable that applies to all serverless resources, or different environment variables for each resource.

Format

The format for passing environment variables to a build container depends on how many environment variables you provide for your resources.

To provide a single environment variable for all resources, specify a Parameters object like the following:

{
  "Parameters": {
    "GITHUB_TOKEN": "TOKEN_GLOBAL"
  }
}

To provide different environment variables for each resource, specify objects for each resource like the following:

{
  "MyFunction1": {
    "GITHUB_TOKEN": "TOKEN1"
  },
  "MyFunction2": {
    "GITHUB_TOKEN": "TOKEN2"
  }
}

Save your environment variables as a file, for example, named env.json. The following command uses this file to pass your environment variables to the build container:

sam build --use-container --container-env-var-file env.json

Precedence

• The environment variables that you provide for specific resources take precedence over the single environment variable for all resources.

• Environment variables that you provide on the command line take precedence over environment variables in a file.

Examples

Example 1: .zip file archive

The following sam build commands build a .zip file archive:

# Build all functions and layers, and their dependencies
sam build

# Run the build process inside a Docker container that functions like a Lambda environment
sam build --use-container

# Build a Node.js 12 application using a container image pulled from DockerHub
sam build --use-container --build-image amazon/aws-sam-cli-build-image-nodejs12.x

# Build a function resource using the Python 3.8 container image pulled from DockerHub
sam build --use-container --build-image Function1=amazon/aws-sam-cli-build-image-python3.8 

# Build and run your functions locally
sam build && sam local invoke

# For more options
sam build --help

Example 2: Container image

The following AWS SAM template builds as a container image:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      PackageType: Image
      ImageConfig:
        Command: ["app.lambda_handler"]
    Metadata:
      Dockerfile: Dockerfile
      DockerContext: ./hello_world
      DockerTag: v1

The following is an example Dockerfile:

FROM public.ecr.aws/lambda/python:3.8

COPY app.py requirements.txt ./

RUN python3.8 -m pip install -r requirements.txt

# Overwrite the command by providing a different command directly in the template.
CMD ["app.lambda_handler"]

Example 3: npm ci

For Node.js applications, you can use npm ci instead of npm install to install dependencies. To use npm ci, specify UseNpmCi: True under BuildProperties in your Lambda function's Metadata resource attribute. To use npm ci, your application must have a package-lock.json or npm-shrinkwrap.json file present in the CodeUri for your Lambda function.

The following example uses npm ci to install dependencies when you run sam build:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: hello-world/
      Handler: app.handler
      Runtime: nodejs14.x
      Architectures:
        - x86_64
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /hello
            Method: get
    Metadata:
      BuildProperties:
        UseNpmCi: True