Build your first worker
Learn how to create, deploy, and test a custom Serverless worker.
For an even faster start, clone 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
- You’ve created a RunPod account.
- You’ve installed Python 3.x and Docker on your local machine and configured them for your command line.
Step 1: Create a Python virtual environment
First, set up a virtual environment to manage your project dependencies.
Create a virtual environment
Run this command in your local terminal:
Activate the virtual environment
Install the RunPod SDK
Step 2: Create a handler file
Create a file named rp_handler.py
and add the following code:
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 Python code for generating images, text, or running any machine learning workload.
Step 3: Create a test input file
You’ll need to create an input file to properly test your handler locally. Create a file named test_input.json
and add the following code:
Step 4: Test your handler locally
Run your handler to verify that it works correctly:
You should see output similar to this:
Step 5: Create a Dockerfile
Create a file named Dockerfile
with the following content:
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:
Build your Docker image
Build your Docker image, specifying the platform for RunPod deployment, replacing [YOUR_USERNAME]
with your Docker username:
Push the image to your container registry
Step 7: Deploy your worker using the RunPod console
To deploy your worker to a Serverless endpoint:
- Go to the Serverless section of the RunPod console.
- Click New Endpoint.
- Under Custom Source, select Docker Image, then click Next.
- In the Container Image field, enter your Docker image URL:
docker.io/yourusername/serverless-test:latest
. - (Optional) Enter a custom name for your endpoint, or use the randomly generated name.
- Under Worker Configuration, check the box for 16 GB GPUs.
- Leave the rest of the settings at their defaults.
- Click Create 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:
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:
Congratulations! You’ve successfully deployed and tested your first Serverless worker.
Next steps
Now that you’ve learned the basics, you’re ready to:
- Create more advanced handler functions.
- Send endpoint requests using cURL and the Serverless SDK.
- Learn how to use endpoint operations like
/run
and/status
. - Manage your Serverless endpoints using the RunPod console.
- Configure your endpoints for optimal performance and cost.
- Learn more about local testing.