Skip to main content
After creating a Dockerfile for your worker, you can build the image, test it locally, and deploy it to a Serverless endpoint.

​
Requirements

​
Build 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:VERSION .
Replace DOCKER_USERNAME with your Docker Hub username, WORKER_NAME with a descriptive name for your worker, and VERSION with an appropriate version tag.
The --platform linux/amd64 flag is required to ensure compatibility with Runpod’s infrastructure. This is especially important if you’re building on an ARM-based system (like Apple Silicon Macs), as the default platform would be incompatible with Runpod’s infrastructure.

​
Test the image locally

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

​
Push 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:VERSION
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:VERSION

# Use the SHA when deploying
# DOCKER_USERNAME/WORKER_NAME:VERSION@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.

​
Deploy an endpoint

If your files are hosted on GitHub, you can deploy your worker directly from a GitHub repository through the Runpod console.
You can deploy your worker image directly from a Docker registry through the Runpod console:
  1. Navigate to the Serverless section of the Runpod console.
  2. Click New Endpoint.
  3. Click Import from Docker Registry.
  4. In the Container Image field, enter your Docker image URL (e.g., docker.io/yourusername/worker-name:v1.0.0), then click Next.
  5. 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 (active/max workers, timeouts, environment variables).
  6. Click Deploy Endpoint to deploy your worker.

​
Troubleshoot 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.