Python Deploy uses Docker backed Lambda functions. This means that your application must live inside a Docker image, which is then pushed to ECR and deployed to Lambda.

To build and deploy your application you need to have Docker and pd_cli.

You can use pipx to install pd_cli globally in your environment, or add it as a dependency in you existing project.

# Globally available
pipx install "pd_cli~=1.0"

# As a dependency in your project using Poetry
poetry add "pd_cli~=1.0"

Building the image

To build your Docker image you need a Dockerfile. This is an example file that should help you get started:

# Select the base image to use.
FROM python:3.8

# Define function directory
ARG FUNCTION_DIR="/function"

# Set working directory to function root directory

# Install the AWS runtime interface and the PythonDeploy clients
# We recommend that you add these as dependencies to your project
# instead of adding them here.
RUN pip install \
        awslambdaric pd_aws_lambda

COPY requirements.txt .

RUN pip install -r requirements.txt

# Copy function code
COPY . .

# Important!
# These instructions are required for your image to be compatible with
# AWS Lambda and Python Deploy.
ENTRYPOINT [ "/usr/local/bin/python", "-m", "awslambdaric" ]
CMD [ "pd_aws_lambda.dispatcher.dispatcher" ]

Save the file as Dockerfile in the root of your project, and then run the following command:

# Use Docker cli directly
docker build -t python-deploy:release .

# You can also use python-deploy cli
# This is useful for CI/CD workflows with as Docker in Docker.
python-deploy build python-deploy:release

That command will build your image and tag it as python-deploy:release. The tag name is arbitrary, and you can change it if you need to use a different tag for your workflow.

We will use the tag to deploy the image to you Lambda functions.

Deploying the image

Once you have the image that you want to use, you use the python-deploy cli to push it to your ECR repository (created for you by Python Deploy), and then launch the Lambda functions with the new image.

# Expected environment variables:
# PD_APP_ID=00000000-0000-0000-0000-000000000000
# PD_API_KEY=0000000000000000000000000000000000000000

python-deploy deploy python-deploy:release

  • PD_API_KEY - The api key that you get to authenticate with Python Deploy. You can find it in your user profile page.
  • PD_APP_ID - The unique ID of the app that you are deploying. This is shown inside each application's page.

You can also pass those values directly to python-deploy as --app-id and --api-key, but this is usually discouraged to avoid having them in your shell history.

After the command finishes, your application now uses your new Docker image.

Executing post-deploy commands

It is common to have applications that need to run commands after new code has been deployed, like database migrations.

The python-deploy cli allows you to run one-time commands in you Tasks Lambda function.

# Expected environment variables:
# PD_APP_ID=00000000-0000-0000-0000-000000000000
# PD_API_KEY=0000000000000000000000000000000000000000

# Deploy you image and wait until it is live
python-deploy deploy python-deploy:release --wait

# Run Django migrations
python-deploy run -- python3 migrate

The stdout and stderr of the command will redirected to the equivalents in your current shell.

Something missing? → [email protected]