Skip to main content
Learn how to package a handler function into a Docker image and deploy it as a Serverless worker on Runpod.

​
Requirements

To deploy a worker image, you need:

​
Project organization

Organize your project files in a directory structure like this: 
project_directory
├── Dockerfile              # Instructions for building the Docker image
├── src
│   └── handler.py          # Your handler function
└── builder
    └── requirements.txt    # Dependencies required by your handler
Your requirements.txt file should list all Python packages your handler needs: 
# Example requirements.txt
runpod~=1.7.6
torch==2.0.1
pillow==9.5.0
transformers==4.30.2

​
Creating a Dockerfile

The Dockerfile tells Docker how to build your worker image. Create a file named Dockerfile (no extension) in your project’s root directory: 
FROM python:3.11.1-slim

WORKDIR /

# Copy and install requirements
COPY builder/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy your handler code
COPY src/handler.py .

# Command to run when the container starts
CMD ["python", "-u", "/handler.py"]
This Dockerfile starts with a Python base image, installs your dependencies, copies your handler code, and specifies the command to run when the container starts.

​
Including models and external files

If your handler uses machine learning models or other external files, include them in the Docker image: 
FROM python:3.11.1-slim

WORKDIR /

# Copy and install requirements
COPY builder/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy your code and model files
COPY src/handler.py .
COPY models/ /models/

# Set environment variables if needed
ENV MODEL_PATH=/models/my_model.pt

# Command to run when the container starts
CMD ["python", "-u", "/handler.py"]
Always include your model files directly in the Docker image rather than downloading them at runtime to ensure faster startup times and more reliable execution.

​
Building the Docker image

From your terminal, navigate to your project directory and build the Docker image: 
docker build --platform linux/amd64 -t [DOCKER_USERNAME]/[WORKER_NAME]:v1.0.0 .
Replace [DOCKER_USERNAME] with your Docker Hub username, [WORKER_NAME] with a descriptive name for your worker, and v1.0.0 with an appropriate version tag.
The --platform linux/amd64 flag is required to ensure compatibility with Runpod’s infrastructure.

​
Testing your image locally

Before pushing it to the registry, you should test your Docker image locally: 
docker run -it [DOCKER_USERNAME]/[WORKER_NAME]:v1.0.0
If your handler is properly configured with a test input, you should see it process the test input and provide output.

​
Pushing the image to Docker Hub

Make your image available to Runpod by pushing it to Docker Hub: 
# Log in to Docker Hub
docker login

# Push the image
docker push [DOCKER_USERNAME]/[WORKER_NAME]:v1.0.0
Once your image is in the Docker container registry, you can create a Serverless endpoint through the Runpod console.

​
Image versioning

For production workloads, use SHA tags for absolute reproducibility: 
# Get the SHA after pushing
docker inspect --format='{{index .RepoDigests 0}}' [DOCKER_USERNAME]/[WORKER_NAME]:v1.0.0

# Use the SHA when deploying
# [DOCKER_USERNAME]/[WORKER_NAME]:v1.0.0@sha256:4d3d4b3c5a5c2b3a5a5c3b2a5a4d2b3a2b3c5a3b2a5d2b3a3b4c3d3b5c3d4a3
Versioning best practices:
  • Never rely on the :latest tag for production.
  • Use semantic versioning AND SHA tags for clarity and reproducibility.
  • Document the specific image SHA in your deployment documentation.
  • Keep images as small as possible for faster startup times.

​
Troubleshooting deployment issues

If your worker fails to start or process requests:
  1. Check the logs in the Runpod console for error messages.
  2. Verify your handler function works correctly in local testing.
  3. Ensure all dependencies are properly installed in the Docker image.
  4. Check that your Docker image is compatible with the selected GPU type.
  5. Verify your input format matches what your handler expects.

​
Deploying from AWS ECR

You can deploy Serverless workers from AWS Elastic Container Registry (ECR), but this requires additional setup due to ECR’s credential expiration policy. To deploy from ECR, you’ll need:
  • An AWS account with ECR access.
  • An ECR repository containing your worker image.
  • A Runpod account with API access.

​
Setting up credential automation

ECR credentials expire every 12 hours, so you’ll need to automate credential updates. The recommended approach is to use an AWS Lambda function that refreshes your Runpod container registry credentials:
  1. Create an AWS Lambda function that runs every few hours to refresh ECR credentials.
  2. Configure the Lambda function to call Runpod’s container registry API to programmatically update stored credentials.
You can use the Runpod GraphQL API saveRegistryAuth mutation to programmatically update credentials in your Lambda function.

​
Deploying your ECR image

Once you have credential automation in place:
  1. Push your image to ECR following standard ECR procedures.
  2. Configure container registry credentials in the Runpod console with your ECR repository URL and current credentials.
  3. Create your Serverless endpoint using the ECR image URL for the Container Image field: [AWS_ACCOUNT_ID].dkr.ecr.[REGION].amazonaws.com/[REPOSITORY_NAME]:[TAG]

​
Next steps

After successfully deploying your worker, you can:
⌘I