Package and deploy a worker image
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:
- A working handler function.
- Docker installed on your development machine.
- A Docker Hub account.
Project organization
Organize your project files in a directory structure like this:
Your requirements.txt
file should list all Python packages your handler needs:
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:
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:
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:
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:
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:
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:
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:
- Check the logs in the RunPod console for error messages.
- Verify your handler function works correctly in local testing.
- Ensure all dependencies are properly installed in the Docker image.
- Check that your Docker image is compatible with the selected GPU type.
- Verify your input format matches what your handler expects.
Next steps
After successfully deploying your worker, you can: