> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Lambda Tutorial

> Build applications using Minimus container images to run on AWS Lambda

AWS Lambda supports deploying functions as Docker container images via Amazon ECR. Container images allow richer dependency management and a higher size limit (10 GB) than zip-based deployments, but Lambda requires images to conform to a specific format. [See AWS docs](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html)

This tutorial builds a Python Lambda function using a multi-stage Dockerfile: the build stage uses `reg.mini.dev/python:latest-dev` for access to `pip`, and the runtime stage uses the fully distroless production image for a minimal, secure final artifact. [Learn more about multi-stage builds](https://docs.minimus.io/guides/multi-stage-build)

## What this guide demonstrates

* Minimus Python images can run on AWS Lambda
* Amazon Linux is not required
* Non-root execution is supported
* Buildx defaults must be overridden

## Prerequisites

* Access to an AWS account
* Permission to:
  * Create ECR repositories
  * Push images to ECR
  * Create and invoke Lambda functions
    * Access to create or use a role for the function
  * Read CloudWatch logs

## Process

<Steps>
  <Step title="Create Python app">
    Create a Python app `app.py`:

    ```python app.py theme={null}
    import sys
    import os

    def handler(event, context):
        return {
            "ok": True,
            "python": sys.version,
            "cwd": os.getcwd(),
            "uid": os.getuid(),
            "event": event,
        }
    ```
  </Step>

  <Step title="Create Dockerfile">
    Save the following Dockerfile. The build stage creates an isolated `venv` (virtual environment) so runtime dependencies can be copied cleanly to the production image:

    ```shellscript Dockerfile expandable lines theme={null}
    # === Build Stage ===

    FROM reg.mini.dev/python:latest-dev AS builder

    WORKDIR /var/task

    # Create an isolated venv for runtime dependencies (including awslambdaric)

    RUN python -m venv /opt/venv

    ENV PATH="/opt/venv/bin:\$PATH"

    # Install the Lambda Runtime Interface Client (RIC) into the venv
    # Add other dependencies if relevant (requirements.txt)

    RUN pip install --no-cache-dir awslambdaric

    # === Runtime Stage ===

    FROM reg.mini.dev/python:latest

    # Lambda expects code in /var/task

    WORKDIR /var/task

    COPY app.py .

    # Copy the pre-built venv from the builder stage

    COPY --from=builder /opt/venv /opt/venv

    # Use venv python and packages at runtime

    ENV PATH="/opt/venv/bin:\$PATH"

    ENV HOME=/home/python

    USER 1000

    # Lambda container contract:
    # ENTRYPOINT starts the runtime interface client
    # CMD names the handler

    ENTRYPOINT ["python", "-m", "awslambdaric"]

    CMD ["app.handler"]
    ```
  </Step>

  <Step title="Create an ECR repository">
    Create an ECR repository. [See AWS docs](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-cli.html#cli-create-repository)  

    In the AWS Console:

    1. Go to Elastic Container Registry (ECR)
    2. Create a private repository. For this guide, we assume you named it: `minimus-lambda-example`
    3. Note the full repository URI, for example:
       `123456789012.dkr.ecr.eu-north-1.amazonaws.com/minimus-lambda-example`
  </Step>

  <Step title="Authenticate to your default registry">
    Authenticate the Docker CLI to your default registry so the **docker** command can push and pull images with Amazon ECR. [See AWS docs](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-cli.html#cli-authenticate-registry)

    ```shellscript theme={null}
    aws ecr get-login-password --region eu-north-1 \
      | docker login --username AWS --password-stdin \
        123456789012.dkr.ecr.eu-north-1.amazonaws.com
    ```

    Replace the example URI in the above command with your own before running the command.
  </Step>

  <Step title="Build and push the image">
    Build the image using buildx. Buildx is an extended Docker build command that uses BuildKit under the hood, handling multi-architecture builds, remote push, and more.

    ```shellscript theme={null}
    docker buildx build \
      --platform linux/arm64 \
      --provenance=false \
      --sbom=false \
      -t 123456789012.dkr.ecr.eu-north-1.amazonaws.com/minimus-lambda-example:lambda-arm64 \
      --push \
      .
    ```
  </Step>

  <Step title="Create the Lambda function">
    In the AWS Console:

    1. Go to Lambda
    2. Click **Create function**
    3. Select container image
    4. Select `minimus-lambda-example:lambda-arm64`
    5. Set Architecture to `arm64`
    6. Create or select an execution role
    7. Create the function
  </Step>

  <Step title="Invoke via AWS CLI">
    Create a test event:

    ```shellscript theme={null}
    echo '{"hello":"lambda"}' > event.json
    ```

    Invoke the function:

    <CodeGroup>
      ```shellscript theme={null}
      aws lambda invoke \
        --function-name minimus-lambda-example \
        --payload file://event.json \
        --cli-binary-format raw-in-base64-out \
        --region eu-north-1 \
        response.json
      ```
    </CodeGroup>

    View the response:

    <CodeGroup>
      ```shellscript theme={null}
      cat response.json
      ```

      ```json Expected output theme={null}
      {"ok": true, "python": "3.14.2 (tags/v3.14.2-0-gdf79316-dirty:df79316, Dec  5 2025, 20:23:01) [GCC 15.2.0]", "cwd": "/var/task", "uid": 993, "event": {"hello": "lambda"}}%
      ```
    </CodeGroup>
  </Step>

  <Step title="Invoke via AWS console">
    1. Open the Lambda function
    2. Click **Test**
    3. Create a new test event:

    ```json theme={null}
    {

      "hello": "lambda"

    }
    ```

    4. Invocation type: **Synchronous**
    5. Click **Test**
  </Step>
</Steps>

## Required Buildx flags

Lambda requires a single-architecture image manifest, not an OCI index with attestations. Docker Buildx adds provenance and SBOM attestations by default, which results in the pushed image becoming an OCI image index containing an extra attestation manifest (often shown as `unknown/unknown` platform). Since AWS Lambda does not support this image format, it is necessary to add the following Buildx flags:

* `--provenance=false`
* `--sbom=false`

If the above flags are omitted, Lambda creation fails with the error: `The image manifest, config or layer media type is not supported`.