Skip to main content
For an even faster start, clone or download the worker-basic repository for a pre-configured template for building and deploying Serverless workers. After cloning the repository, skip to step 6 of this tutorial to deploy and test the endpoint.

​
What you’ll learn

In this tutorial you’ll learn how to:
  • Set up your development environment.
  • Create a handler file.
  • Test your handler locally.
  • Build a Docker image for deployment.
  • Deploy and test your worker on the Runpod console.

​
Requirements

​
Step 1: Set up your project directory

Use the command line to set up your project directory and a virtual environment to manage dependencies.
1

Create a directory for your project and navigate to it

mkdir serverless-worker-tutorial
cd serverless-worker-tutorial
2

Create a virtual environment

python3 -m venv venv
3

Activate the Python virtual environment

  • macOS/Linux
  • Windows
source venv/bin/activate
4

Install the Runpod SDK

pip install runpod
5

Create the necessary project files

touch rp_handler.py test_input.json Dockerfile
This creates the following empty files in your project directory, which we’ll build out in the next few steps of this tutorial:
  • rp_handler.py: Your handler function, which will contain your custom logic for processing requests to your Serverless endpoint.
  • test_input.json: A test input file for local testing of your handler function.
  • Dockerfile: Instructions for building your handler function into a Docker image for deployment to Runpod.

​
Step 2: Create a handler file

Using a text editor of your choice, add the following code to your rp_handler.py file: 
import runpod
import time  

def handler(event):
#   This function processes incoming requests to your Serverless endpoint.
#
#    Args:
#        event (dict): Contains the input data and request metadata
#       
#    Returns:
#       Any: The result to be returned to the client
    
    # Extract input data
    print(f"Worker Start")
    input = event['input']
    
    prompt = input.get('prompt')  
    seconds = input.get('seconds', 0)  

    print(f"Received prompt: {prompt}")
    print(f"Sleeping for {seconds} seconds...")
    
    # You can replace this sleep call with your own custom Python code
    time.sleep(seconds)  
    
    return prompt 

# Start the Serverless function when the script is run
if __name__ == '__main__':
    runpod.serverless.start({'handler': handler })
This is a bare-bones handler that processes a JSON object and outputs a prompt string contained in the input object. You can replace the time.sleep(seconds) call with your own custom Python code for generating images, text, or running any machine learning workload.

​
Step 3: Create a test input file

Add the following lines to your test_input.json file: 
{
    "input": {
        "prompt": "Hey there!"
    }
}

​
Step 4: Test your handler locally

Use the command line to test your handler locally: 
python rp_handler.py
You should see output similar to this in your terminal: 
--- Starting Serverless Worker |  Version 1.7.9 ---
INFO   | Using test_input.json as job input.
DEBUG  | Retrieved local job: {'input': {'prompt': 'Hey there!'}, 'id': 'local_test'}
INFO   | local_test | Started.
Worker Start
Received prompt: Hey there!
Sleeping for 0 seconds...
DEBUG  | local_test | Handler output: Hey there!
DEBUG  | local_test | run_job return: {'output': 'Hey there!'}
INFO   | Job local_test completed successfully.
INFO   | Job result: {'output': 'Hey there!'}
INFO   | Local testing complete, exiting.

​
Step 5: Create a Dockerfile

Add the following instructions to your Dockerfile: 
FROM python:3.10-slim

WORKDIR /

# Install dependencies
RUN pip install --no-cache-dir runpod

# Copy your handler file
COPY rp_handler.py /

# Start the container
CMD ["python3", "-u", "rp_handler.py"]

​
Step 6: Build and push your Docker image

Instead of building and pushing your image via Docker Hub, you can also deploy your worker from a GitHub repository.
Before you can deploy your worker on Runpod Serverless, you need to push it to Docker Hub:
1

Build your Docker image

Use the command line to build your Docker image, specifying the platform for Runpod deployment, replacing DOCKER_USERNAME with your Docker Hub username:
docker build --platform linux/amd64 \
--tag DOCKER_USERNAME/serverless-worker-tutorial .
2

Push the image to your container registry

docker push DOCKER_USERNAME/serverless-worker-tutorial:latest

​
Step 7: Deploy your worker using the Runpod console

To deploy your worker to a Serverless endpoint:
  1. Go 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: docker.io/DOCKER_USERNAME/serverless-worker-tutorial:latest.
  5. Click Next to proceed to endpoint configuration.
  6. Configure your endpoint settings:
    • (Optional) Enter a custom name for your endpoint, or use the randomly generated name.
    • Make sure the Endpoint Type is set to Queue.
    • Under GPU Configuration, check the box for 16 GB GPUs.
    • Leave the rest of the settings at their defaults.
  7. Click Deploy Endpoint.
The system will redirect you to a dedicated detail page for your new endpoint.

​
Step 8: Test your worker

To test your worker, click the Requests tab in the endpoint detail page:
On the left you should see the default test request: 
{
    "input": {
        "prompt": "Hello World"
    }
}
Leave the default input as is and click Run. The system will take a few minutes to initialize your workers. When the workers finish processing your request, you should see output on the right side of the page similar to this: 
{
    "delayTime": 15088,
    "executionTime": 60,
    "id": "04f01223-4aa2-40df-bdab-37e5caa43cbe-u1",
    "output": "Hello World",
    "status": "COMPLETED",
    "workerId": "uhbbfre73gqjwh"
}
Congratulations! You’ve successfully deployed and tested your first Serverless worker.

​
Next steps

Now that you’ve learned the basics, you’re ready to: