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: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 namedDockerfile
(no extension) in your project’s root directory:
Including models and external files
If your handler uses machine learning models or other external files, include them in the Docker image:Building the Docker image
From your terminal, navigate to your project directory and build the Docker image:[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 an image locally
Before pushing it to the registry, you should test your Docker image locally:Pushing the image to Docker Hub
Make your image available to Runpod by pushing it to Docker Hub:Image versioning
For production workloads, use SHA tags for absolute reproducibility:- 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.
Deploy an endpoint
You can deploy your worker image directly from a Docker registry through the Runpod console:- Navigate to the Serverless section of the Runpod console.
- Click New Endpoint.
- Click Import from Docker Registry.
- In the Container Image field, enter your Docker image URL (e.g.,
docker.io/yourusername/worker-name:v1.0.0
), then click Next. - Configure your endpoint settings:
- Enter an Endpoint Name.
- Choose your Endpoint Type: select Queue for traditional queue-based processing or Load Balancer for direct HTTP access (see Load balancing endpoints for details).
- Under GPU Configuration, select the appropriate GPU types for your workload.
- Configure other settings as needed (workers, timeouts, environment variables).
- Click Deploy Endpoint to deploy your worker.
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.