├── .gitignore ├── .runpod ├── hub.json └── tests.json ├── Dockerfile ├── LICENSE ├── README.md ├── handler.py ├── public └── worker-template_banner.jpeg ├── requirements.txt └── test_input.json /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | share/python-wheels/ 24 | *.egg-info/ 25 | .installed.cfg 26 | *.egg 27 | MANIFEST 28 | 29 | # PyInstaller 30 | # Usually these files are written by a python script from a template 31 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 32 | *.manifest 33 | *.spec 34 | 35 | # Installer logs 36 | pip-log.txt 37 | pip-delete-this-directory.txt 38 | 39 | # Unit test / coverage reports 40 | htmlcov/ 41 | .tox/ 42 | .nox/ 43 | .coverage 44 | .coverage.* 45 | .cache 46 | nosetests.xml 47 | coverage.xml 48 | *.cover 49 | *.py,cover 50 | .hypothesis/ 51 | .pytest_cache/ 52 | cover/ 53 | 54 | # Translations 55 | *.mo 56 | *.pot 57 | 58 | # Django stuff: 59 | *.log 60 | local_settings.py 61 | db.sqlite3 62 | db.sqlite3-journal 63 | 64 | # Flask stuff: 65 | instance/ 66 | .webassets-cache 67 | 68 | # Scrapy stuff: 69 | .scrapy 70 | 71 | # Sphinx documentation 72 | docs/_build/ 73 | 74 | # PyBuilder 75 | .pybuilder/ 76 | target/ 77 | 78 | # Jupyter Notebook 79 | .ipynb_checkpoints 80 | 81 | # IPython 82 | profile_default/ 83 | ipython_config.py 84 | 85 | # pyenv 86 | # For a library or package, you might want to ignore these files since the code is 87 | # intended to run in multiple environments; otherwise, check them in: 88 | # .python-version 89 | 90 | # pipenv 91 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 92 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 93 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 94 | # install all needed dependencies. 95 | #Pipfile.lock 96 | 97 | # poetry 98 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. 99 | # This is especially recommended for binary packages to ensure reproducibility, and is more 100 | # commonly ignored for libraries. 101 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control 102 | #poetry.lock 103 | 104 | # pdm 105 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. 106 | #pdm.lock 107 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it 108 | # in version control. 109 | # https://pdm.fming.dev/#use-with-ide 110 | .pdm.toml 111 | 112 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm 113 | __pypackages__/ 114 | 115 | # Celery stuff 116 | celerybeat-schedule 117 | celerybeat.pid 118 | 119 | # SageMath parsed files 120 | *.sage.py 121 | 122 | # Environments 123 | .env 124 | .venv 125 | env/ 126 | venv/ 127 | ENV/ 128 | env.bak/ 129 | venv.bak/ 130 | 131 | # Spyder project settings 132 | .spyderproject 133 | .spyproject 134 | 135 | # Rope project settings 136 | .ropeproject 137 | 138 | # mkdocs documentation 139 | /site 140 | 141 | # mypy 142 | .mypy_cache/ 143 | .dmypy.json 144 | dmypy.json 145 | 146 | # Pyre type checker 147 | .pyre/ 148 | 149 | # pytype static type analyzer 150 | .pytype/ 151 | 152 | # Cython debug symbols 153 | cython_debug/ 154 | 155 | # PyCharm 156 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can 157 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore 158 | # and can be added to the global gitignore or merged into this file. For a more nuclear 159 | # option (not recommended) you can uncomment the following to ignore the entire idea folder. 160 | #.idea/ 161 | -------------------------------------------------------------------------------- /.runpod/hub.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "Worker Template", 3 | "description": "A starting point for creating your own custom serverless worker. It provides a basic structure and configuration that you can build upon.", 4 | "type": "serverless", 5 | "category": "language", 6 | "iconUrl": "https://dummyimage.com/100x100/5733ff/fff&text=SW", 7 | "config": { 8 | "runsOn": "GPU", 9 | "containerDiskInGb": 5, 10 | "gpuIds": "ADA_24", 11 | "gpuCount": 1, 12 | "allowedCudaVersions": [ 13 | "12.7", 14 | "12.6", 15 | "12.5", 16 | "12.4", 17 | "12.3", 18 | "12.2", 19 | "12.1" 20 | ] 21 | } 22 | } -------------------------------------------------------------------------------- /.runpod/tests.json: -------------------------------------------------------------------------------- 1 | { 2 | "tests": [ 3 | { 4 | "name": "basic_test", 5 | "input": { 6 | "name": "John Doe" 7 | }, 8 | "timeout": 10000 9 | } 10 | ], 11 | "config": { 12 | "gpuTypeId": "NVIDIA GeForce RTX 4090", 13 | "gpuCount": 1, 14 | "allowedCudaVersions": [ 15 | "12.7", 16 | "12.6", 17 | "12.5", 18 | "12.4", 19 | "12.3", 20 | "12.2", 21 | "12.1" 22 | ] 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM runpod/base:0.6.3-cuda11.8.0 2 | 3 | # Set python3.11 as the default python 4 | RUN ln -sf $(which python3.11) /usr/local/bin/python && \ 5 | ln -sf $(which python3.11) /usr/local/bin/python3 6 | 7 | # Install dependencies 8 | COPY requirements.txt /requirements.txt 9 | RUN uv pip install --upgrade -r /requirements.txt --no-cache-dir --system 10 | 11 | # Add files 12 | ADD handler.py . 13 | 14 | # Run the handler 15 | CMD python -u /handler.py 16 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 RunPod 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![RunPod Worker Template](https://cpjrphpz3t5wbwfe.public.blob.vercel-storage.com/worker-template_banner-zUuCAjwDuvfsINR6vKBhYvvm3TnZFB.jpeg) 2 | 3 | --- 4 | 5 | This repository serves as a starting point for creating your own custom RunPod Serverless worker. It provides a basic structure and configuration that you can build upon. 6 | 7 | --- 8 | 9 | [![RunPod](https://api.runpod.io/badge/runpod-workers/worker-template)](https://www.runpod.io/console/hub/runpod-workers/worker-template) 10 | 11 | --- 12 | 13 | ## Getting Started 14 | 15 | 1. **Use this template:** Create a new repository based on this template or clone it directly. 16 | 2. **Customize:** Modify the code and configuration files to implement your specific task. 17 | 3. **Test:** Run your worker locally to ensure it functions correctly. 18 | 4. **Deploy:** Connect your repository to RunPod or build and push the Docker image manually. 19 | 20 | ## Customizing Your Worker 21 | 22 | - **`handler.py`:** This is the core of your worker. 23 | - The `handler(event)` function is the entry point executed for each job. 24 | - The `event` dictionary contains the job input under the `"input"` key. 25 | - Modify this function to load your models, process the input and return the desired output. 26 | - Consider implementing model loading outside the handler (e.g., globally or in an initialization function) if models are large and reused across jobs. 27 | - **`requirements.txt`:** Add any Python libraries your worker needs to this file. These will be installed via `uv` when the Docker image is built. 28 | - **`Dockerfile`:** 29 | - This file defines the Docker image for your worker. 30 | - It starts from a [RunPod base image (`runpod/base`)](https://github.com/runpod/containers/tree/main/official-templates/base) which includes CUDA, mulitple versions of python, uv, jupyter notebook and common dependencies. 31 | - It installs dependencies from `requirements.txt` using `uv`. 32 | - It copies your `src` directory into the image. 33 | - You might need to add system dependencies (`apt-get install ...`), environment variables (`ENV`), or other setup steps here if required by your specific application. 34 | - **`test_input.json`:** Modify this file to provide relevant sample input for local testing. 35 | 36 | ## Testing Locally 37 | 38 | You can test your handler logic locally using the RunPod Python SDK. For detailed steps on setting up your local environment (creating a virtual environment, installing dependencies) and running the handler, please refer to the [RunPod Serverless Get Started Guide](https://docs.runpod.io/serverless/get-started). 39 | 40 | 1. **Prepare Input:** Modify `test_input.json` with relevant sample input for your handler. 41 | 2. **Run the Handler:** 42 | ```bash 43 | python handler.py 44 | ``` 45 | This will execute your `handler` function with the contents of [`test_input.json`](/test_input.json) as input. 46 | 47 | ## Deploying to RunPod 48 | 49 | There are two main ways to deploy your worker: 50 | 51 | 1. **GitHub Integration (Recommended):** 52 | 53 | - Connect your GitHub repository to RunPod Serverless. RunPod will automatically build and deploy your worker whenever you push changes to your specified branch. 54 | - For detailed instructions on setting up the GitHub integration, authorizing RunPod, and configuring your deployment, please refer to the [RunPod Deploy with GitHub Guide](https://docs.runpod.io/serverless/github-integration). 55 | 56 | 2. **Manual Docker Build & Push:** 57 | - For detailed instructions on building the Docker image locally and pushing it to a container registry, please see the [RunPod Serverless Get Started Guide](https://docs.runpod.io/serverless/get-started#step-6-build-and-push-your-docker-image). 58 | - Once pushed, create a new Template or Endpoint in the RunPod Serverless UI and point it to the image in your container registry. 59 | 60 | ## Further Information 61 | 62 | - [RunPod Serverless Documentation](https://docs.runpod.io/serverless/overview) 63 | - [Python SDK](https://github.com/runpod/runpod-python) 64 | - [Base Docker Images](https://github.com/runpod/containers/tree/main/official-templates/base) 65 | - [Community Discord](https://discord.gg/cUpRmau42Vd) 66 | -------------------------------------------------------------------------------- /handler.py: -------------------------------------------------------------------------------- 1 | """Example handler file.""" 2 | 3 | import runpod 4 | 5 | # If your handler runs inference on a model, load the model here. 6 | # You will want models to be loaded into memory before starting serverless. 7 | 8 | 9 | def handler(job): 10 | """Handler function that will be used to process jobs.""" 11 | job_input = job["input"] 12 | 13 | name = job_input.get("name", "World") 14 | 15 | return f"Hello, {name}!" 16 | 17 | 18 | runpod.serverless.start({"handler": handler}) 19 | -------------------------------------------------------------------------------- /public/worker-template_banner.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpod-workers/worker-template/03ea230656c21f789cf67b4b09aebb824348a9ed/public/worker-template_banner.jpeg -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | # Required Python packages get listed here, one per line. 2 | 3 | runpod~=1.7.9 -------------------------------------------------------------------------------- /test_input.json: -------------------------------------------------------------------------------- 1 | { 2 | "input": { 3 | "name": "John Doe" 4 | } 5 | } 6 | --------------------------------------------------------------------------------