--mount=type=secret,... needs to be included for every instruction that requires the secret file.
Read more about Docker secrets and secret mounts in the [Docker Docs](https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information).
### Building Images with Secrets Locally
To build images locally with Dockerfiles that make use of secrets, you need to have a recent version of Docker installed.
When you run `docker build`, ensure that BuildKit is enabled with the `DOCKER_BUILDKIT=1` and pass in secrets using the `--secret` argument like so:
```bash
DOCKER_BUILDKIT=1 docker build --secret id=FILENAME,src=LOCAL_FILENAME ...
```
`FILENAME` is the same as the ID from `--mount=type=secret,id=FILENAME,...` in your Dockerfile and `LOCAL_FILENAME` is an appropriate secret file located on your build host.
Read more about Docker secrets and secret mounts in the [Docker Docs](https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information).
## Accessing Secret Files at Runtime
If you add [secret files](configure-environment-variables#secret-files) to a Docker-based service, those services are available at runtime at `/etc/secrets/ARG instructions for secrets. Consider
> using secret files instead for
> build-time secrets.
# Native Runtimes
Render services provide *native runtimes* that enable you to build and deploy your application using common language environments.
Render's native runtimes include:
- Automated builds and deploys for supported languages in both public and private Git repositories
- [Infrastructure as Code](infrastructure-as-code) support with [`render.yaml`](blueprint-spec)
- Regular updates to native runtimes to improve functionality, security, and performance
All native runtimes come with standard Render features like:
- [Private networking](private-services), load balancing, and service discovery
- [Persistent block storage](disks)
- Automatic [Brotli](https://en.wikipedia.org/wiki/Brotli) and [gzip](https://en.wikipedia.org/wiki/Gzip) compression for faster responses
- Easy HTTP [health checks](deploys#health-checks) and [zero-downtime deploys](deploys#zero-downtime-deploys).
- Automatic [pull request previews](service-previews)
- Native HTTP/2 support
- [DDoS protection](ddos-protection)
- Automatic HTTP → HTTPS redirects
## Available Runtimes
Render provides native runtimes for Node.js / Bun, Python, Ruby, Go, Rust, and Elixir.
For details, see [Supported Languages](language-support).
### Changing a service's runtime
If you've recently created a service with an incorrect runtime, the fastest fix is usually to create a _new_ service with the correct runtime.
You can also change an existing service's runtime in any of the following ways:
- Make an HTTP call to the Render API's [Update service](https://api-docs.render.com/reference/update-service) endpoint.
- Specify a new `runtime` via the `serviceDetails` parameter you provide in your request.
- If you're managing your service with [Render Blueprints](infrastructure-as-code), update the service's `runtime` field in your `render.yaml` file, then sync your Blueprint.
## Tools and utilities
The tools and utilities listed below are available for native builds and deploys.
If your build requires a tool that _isn't_ listed below, you can [deploy with Docker](docker) instead of building natively.
### Builds
- bun
- curl
- ffmpeg
- g++
- gcc
- gettext
- git
- gnupg2
- jq
- libvips-dev
- libvips-tools
- make
- nano
- node
- npm
- pandoc
- pigz
- pnpm
- postgresql-client
- princexml
- python3-dev
- python3-pip
- python3-setuptools
- rsync
- sqlite3
- swig
- typescript
- unzip
- vim
- webpack
- wget
- yarn
- zip
### Deploys
- bun
- curl
- ffmpeg
- g++
- gcc
- gettext
- ghostscript
- git
- gnupg2
- imagemagick
- jq
- libvips-dev
- libvips-tools
- make
- nano
- node
- npm
- pandoc
- pigz
- pnpm
- postgresql-client
- postgresql-client-12
- postgresql-client-13
- postgresql-client-14
- princexml
- python3-dev
- python3-pip
- python3-setuptools
- rsync
- sqlite3
- swig
- typescript
- unzip
- vim
- webpack
- wget
- yarn
- zip
# Environment Variables and Secrets
You can (and should!) use *environment variables* to configure your Render services:
[img]
Environment variables enable you to customize a service's runtime behavior for different environments (such as development, staging, and production). They also protect you from committing secret credentials (such as API keys or database connection strings) to your application source.
In addition to setting environment variables, you can:
- Upload plaintext [secret files](#secret-files) to Render that are available from your service's file system at runtime.
- Create [environment _groups_](#environment-groups) to share a collection of environment variables and secret files across multiple Render services.
## Setting environment variables
> Render sets default values for certain environment variables. [See the list.](environment-variables)
### In the Render Dashboard
1. In the [Render Dashboard](https://dashboard.render.com/), select the service you want to add an environment variable to.
2. Click *Environment* in the left pane.
3. Under *Environment Variables*, click *+ Add Environment Variable*.
- You can also click *Add from .env* to [add environment variables in bulk](#adding-in-bulk-from-a-env-file).
4. Provide a *Key* and *Value* for each new environment variable.
5. Save your changes. You can select one of three options from the dropdown:
[img]
- *Save, rebuild, and deploy:* Render triggers a new build for your service and deploys it with the new environment variables.
- *Save and deploy:* Render redeploys your service's _existing_ build with the new environment variables.
- *Save only:* Render saves the new environment variables _without_ triggering a deploy. Your service will not use the new variables until its next deploy.
That's it! Render saves your environment variables and then kicks off a deploy (unless you selected *Save only*).
#### Adding in bulk from a `.env` file
If you have a local `.env` file, you can bulk-add its environment variables to your service by clicking *Add from .env* on your service's *Environment* page.
Your file must use valid `.env` syntax. Here are some valid variable declarations:
```bash
# Value without quotes (doesn't support whitespace)
KEY_1=value_of_KEY_1
# Value with quotes (supports whitespace)
KEY_2="value of KEY_2"
# Multi-line value
KEY_3="-----BEGIN-----
value
of
KEY_3
-----END-----"
```
### Via Blueprints
If you're using Render [Blueprints](infrastructure-as-code) to represent your infrastructure as code, you can declare environment variables for a service directly in your `render.yaml` file.
> **Don't commit the values of secret credentials to your `render.yaml` file!** Instead, you can declare [placeholder environment variables](blueprint-spec#prompting-for-secret-values) for secret values that you then populate from the Render Dashboard.
Here are common patterns for declaring environment variables in a Blueprint:
```yaml
envVars:
- key: NODE_ENV
value: staging # Set NODE_ENV to the hardcoded string 'staging'
- key: APP_SECRET
generateValue: true # Render generates a random base64-encoded, 256-bit secret for APP_SECRET
- key: DB_URL
fromDatabase: # Set DB_URL to the connection string for the db 'mydb'
name: mydb
property: connectionString
- key: MINIO_ROOT_PASSWORD
fromService: # Copy the MINIO_ROOT_PASSWORD from the private service 'minio'
type: pserv
name: minio
envVarKey: MINIO_ROOT_PASSWORD
- key: STRIPE_API_KEY
sync: false # For security, provide STRIPE_API_KEY in the Render Dashboard
- fromGroup: my-env-group # Link the 'my-env-group' environment group to this service
```
For more details and examples, see the [Blueprint Specification](blueprint-spec#environment-variables).
## Secret files
You can upload **secret files** to Render to make those files available to your service at runtime. These are plaintext files that usually contain one or more secret credentials, such as a private key.
> The combined size of all secret files uploaded to any given service or [environment group](#environment-groups) cannot exceed 1 MB.
1. In the [Render Dashboard](https://dashboard.render.com/), select the service you want to add a secret file to.
2. Click **Environment** in the left pane.
3. Under **Secret Files**, click **+ Add Secret File**.
- You can click the button multiple times to add multiple files.
4. Provide a **Filename** for the secret file.
- At runtime, the secret file is available at `/etc/secrets/
A workflow defines a collection of *tasks* (such as `process_docs` and `process_doc` above) that you can run from your applications. Each task runs in its own compute instance and can spin up _other_ tasks as *subtasks* to efficiently distribute work across hundreds or even thousands of instances.
*Render automatically handles queuing, provisioning, and orchestration of tasks.* Task instances run alongside your other Render [service types](service-types), enabling fast and safe communication over your [private network](private-network).
Task instances usually spin up in under one second, providing a more performant, comprehensive evolution of the [background worker](background-workers) model.
## Core capabilities
| Feature | Description |
|--------|--------|
| *Automatic queuing and orchestration* | Render coordinates every phase of the task lifecycle automatically, from queuing to spin-up to deprovisioning. |
| *Long-running execution* | Each task instance can run for up to 2 hours. A future update will further extend this limit. |
| *Configurable retry logic* | Define [retry behavior](workflows-defining#retry-logic) for each task in the event of failure, with exponential backoff. |
| *Outbound networking* | Task instances can initiate network connections over both the public internet and your [private network](private-network). Task instances cannot receive _incoming_ network connections. |
| *Execution observability* | Track the progress and status of active and completed task runs in the Render Dashboard. |
| *Unified SDK* | Install a single lightweight SDK both to register your tasks and to run them from your applications.
> *The Workflows SDK is currently available only for Python.* SDKs for other languages are coming soon.
|
### Early access limitations
We'll address these limitations in future releases following early access:
- Workflows currently only support Python for defining tasks.
- SDKs for other languages are coming soon.
- It is not yet possible to customize a task's associated compute specs. Currently, every task instance has 1 CPU and 2 GB of RAM.
- Workflows do not provide built-in support for [running tasks](workflows-running) on a schedule.
- To schedule tasks, you can create a [cron job](cronjobs) that runs your tasks on the desired schedule.
- If a workflow belongs to a [network-isolated environment](projects#blocking-cross-environment-traffic), its task instances _cannot_ communicate with other services in that environment over its private network.
- Workflows do not yet support running tasks on [HIPAA-compliant](hipaa-compliance) hosts.
- To prevent accidental PHI exposure, it is not currently possible to create new workflows in a HIPAA-enabled workspace.
## How it works
1. You define workflow tasks as Python functions using the Workflows SDK (support for other languages is coming soon):
```python:main.py
from render_sdk.workflows import task, start
import asyncio
# A basic task
@task
def calculate_square(a: int) -> int:
return a * a
# A task that runs two subtasks in parallel
@task
async def sum_squares(a: int, b: int) -> int:
result1, result2 = await asyncio.gather(
calculate_square(a),
calculate_square(b)
)
return result1 + result2
if __name__ == "__main__":
start() # SDK entry point
```
2. In the [Render Dashboard][dboard], you create a new workflow service and link your Python project repo.
3. Render pulls your repo and performs a build, registering your tasks automatically.
4. You can now run your registered tasks from application code using either the Workflows SDK or the Render API.
## Get started
After your workspace receives early access, you're ready to [create your first workflow!](workflows-tutorial)
## FAQ
###### How do I receive access to Render Workflows?
Request early access for your workspace at [render.com/workflows](workflows).
###### How do I get started with Render Workflows?
After your workspace receives early access, get started with [Your First Workflow](workflows-tutorial).
###### Can I define workflow tasks in a language besides Python?
*Not yet.* SDKs for languages besides Python are coming soon.
###### Can I run tasks from a language besides Python?
*Yes.* You can run tasks by calling the Render API directly instead of using the Python SDK. For details, see [Run Workflow Tasks](workflows-running).
###### Can task instances receive incoming network connections?
*No.* Similar to [background workers](background-workers), your task instances must initiate any required network connections themselves.
# Your First Workflow
> *[Render Workflows](workflows) are in limited early access.*
>
> During the early access period, the Workflows API and SDK might introduce breaking changes.
Welcome to Render Workflows! After early access is enabled for your workspace, follow these steps to register your first task and run it.
## 1. Clone the Python template
> *Workflows currently only support Python for defining tasks.*
>
> SDKs for other languages are coming soon.
As part of creating a workflow, you'll link a GitHub/GitLab/Bitbucket repo that contains your task definitions.
To get started quickly, copy our basic [*Python template*](https://github.com/render-examples/workflows-template-python) on GitHub. On the template page, click *Use this template > Create a new repository* to create your own repo with the template's contents.
### The anatomy of a workflow
Let's look at an excerpt from the template's `main.py` file:
```python:main.py
from render_sdk.workflows import task, start
# Minimal task definition
@task
def calculate_square(a: int) -> int:
return a * a
if __name__ == "__main__":
start() # Workflow entry point
```
This excerpt shows the bare minimum syntax for defining a workflow:
- You define a task by applying the `@task` decorator to any function.
- You call the `start` function on startup to initiate task registration and execution.
Both `@task` and `start` are imported from the [Workflows SDK for Python](workflows-sdk-python), which is the template's only dependency.
## 2. Create a workflow service
1. In the [Render Dashboard][dboard], click **New > Workflow**:
[img]
The workflow creation form appears.
> **Don't see the Workflow service type?**
>
> Make sure you're in a workspace that has received early access to Render Workflows. Request early access at [render.com/workflows](workflows).
2. Link the GitHub/GitLab/Bitbucket repo with your workflow's task definitions.
3. Complete the remainder of the creation form. See guidance for important fields:
| Field | Description |
|--------|--------|
| **Language** | Currently, this is always **Python 3**. Support for other languages is coming soon. |
| **Region** | Your workflow's tasks will run on instances in the specified region. This determines which of your _other_ Render services they can reach over your [private network](private-network). |
| **Build Command** | If you're using the Python example template, this is the following: `pip install -r requirements.txt` Otherwise, provide the command that Render should use to build your workflow. |
| **Start Command** | If you're using the Python example template, this is the following: `python main.py` Otherwise, provide the command that Render should use to start your workflow. |
4. Click **Deploy Workflow**. Render kicks off your workflow's first build, which includes registering your tasks.
That's it! After the build completes, your tasks are officially registered. You can view them from your workflow's **Tasks** page in the [Render Dashboard][dboard]:
[img]
## 3. Execute a task
Now that we have a registered task, let's run it! The quickest way to trigger our first run is from the Render Dashboard:
1. From your workflow's **Tasks** page, click a task to open its **Runs** page.
2. Click **Run Task** in the top-right corner of the page:
[img]
A dialog appears for providing the task's input arguments:
[img]
3. Provide the task's input arguments as a JSON array (e.g., `[5]` for a task that takes a single integer argument, or `[]` for a task that takes zero arguments).
4. Click *Start task*.
Your new task run appears at the top of the *Runs* table.
## Next steps
Congratulations! You've registered and run your first workflow task. Now it's time to start designing your own tasks and running them from application code:
- [Define advanced tasks](workflows-defining) with retries, subtasks, and more.
- [Run your registered tasks](workflows-running) from application code.
- [Test task runs locally](workflows-local-development) for faster development.
# Defining Workflow Tasks
> *[Render Workflows](workflows) are in limited early access.*
>
> During the early access period, the Workflows API and Python SDK might introduce breaking changes.
After you [create your first workflow](workflows-tutorial), you can start defining your own tasks. This article describes supported syntax and configuration options.
## Basic example
> *The Workflows SDK is currently available only for Python.*
>
> SDKs for other languages are coming soon. It is not currently possible to define tasks in languages besides Python.
**Python**
Define a task in your workflow service by applying the `@task` decorator to any function, like so:
```python:main.py
from render_sdk.workflows import task, start
@task #highlight-line
def calculate_square(a: int) -> int:
return a * a
if __name__ == "__main__":
start()
```
This defines a basic task named `calculate_square` that takes a single integer argument and returns its square.
For all supported `@task` options, see the [Python SDK reference](workflows-sdk-python#the-task-decorator).
## Organizing tasks
You can define your workflow's tasks across any number of files in your project repo:
> **When should I run a subtask?**
>
> Subtasks are most helpful when different parts of a larger job benefit from long-running, independent compute.
>
> For simple jobs (such as the very basic example below), it's more efficient to perform the entirety of your logic in a single task.
**Python**
The simple `sum_squares` task below runs two `calculate_square` subtasks:
```python:math_tasks.py
from render_sdk.workflows import task
import asyncio
# A task that runs two subtasks
@task
async def sum_squares(a: int, b: int) -> int: # Must be async to await subtasks
result1, result2 = await asyncio.gather(
calculate_square(a),
calculate_square(b)
)
return result1 + result2
@task
def calculate_square(a: int) -> int:
return a * a
```
**When running subtasks:**
- In most cases, the parent task should be defined as `async`.
- Otherwise, it can't `await` the results of its subtasks.
- You run a subtask by calling the corresponding function (e.g., `calculate_square` above).
- _However_, this call doesn't return the function's defined return value!
- Instead, this kicks off a task run and returns a special `TaskInstance` object.
- As shown, you can `await` this object to obtain the subtask's _actual_ return value.
- Your task _can_ call functions that are _not_ marked as tasks. These functions run and return as normal (they do not spin up their own task instances).
> **A task _can_ run another task defined in a _different_ workflow. However:**
>
> - This requires instead using the Workflows SDK or Render API, as described in [Running Workflow Tasks](workflows-running).
> - This is not tracked as a task/subtask relationship when visualizing task execution in the [Render Dashboard][dboard].
### Parallelizing subtasks
When running subtasks, it's usually helpful to run multiple of them in parallel, such as to chunk a large workload into smaller independent pieces. Common examples include processing batches of images or analyzing different sections of a large document.
**Python**
Use `asyncio.gather` to run multiple subtasks in parallel. In the example below, the `process_photo_upload` task runs a separate `process_image` subtask for each element in its `image_urls` argument:
```python
from render_sdk.workflows import task
import asyncio
@task
async def process_photo_upload(image_urls: list[str]) -> dict:
# Process all images in parallel by running a subtask for each
results = await asyncio.gather( #highlight-line
*[process_image(url) for url in image_urls] #highlight-line
) #highlight-line
num_successful = sum(1 for r in results if r["success"])
num_failed = len(results) - num_successful
return {
"total": len(image_urls),
"processed": num_successful,
"failed": num_failed,
"results": results
}
@task
def process_image(image_url: str) -> dict:
# Image processing logic goes here
return {
"url": image_url,
"thumbnail_url": f"{image_url}_thumb.jpg",
"success": True
}
```
**If you don't use `asyncio.gather` or a similar function, subtasks run serially.**
For example:
```python{3-5}
@task
async def sum_squares_slower(a: int, b: int) -> int:
# ⚠️ Not parallel!
result1 = await calculate_square(a)
result2 = await calculate_square(b) # Runs after first subtask completes
return result1 + result2
@task
def calculate_square(a: int) -> int:
return a * a
```
Serial execution _is_ helpful when running a chain of subtasks that depend on each other. However, it dramatically slows execution for subtasks that are completely independent. Parallelize wherever your use case allows.
# Running Workflow Tasks
> *[Render Workflows](workflows) are in limited early access.*
>
> During the early access period, the Workflows API and Python SDK might introduce breaking changes.
After you [create a workflow](workflows-tutorial) and register tasks, you can start triggering task runs from your applications (such as other Render services).
You can also [manually trigger runs](#running-manually) in the Render Dashboard and CLI to help with testing and debugging.
## First: Create an API key
*Triggering task runs from your code requires a Render API key.*
Create an API key with [these steps](api#1-create-an-api-key), then return here.
## Running with the Workflows SDK
> *The Workflows SDK is currently available only for Python.*
>
> SDKs for other languages are coming soon. To execute tasks from other languages, [use the Render API](#running-with-the-render-api).
Follow these steps to execute workflow tasks from application code using the Workflows SDK.
### 1. Install the SDK
**Python**
```shell
pip install render_sdk
```
Make sure to add `render_sdk` to your application's `requirements.txt` file (or equivalent).
### 2. Set your API key
In your application's environment, set the `RENDER_API_KEY` environment variable to your [API key](#first-create-an-api-key):
```bash
export RENDER_API_KEY=rnd_abc123…
```
The SDK client automatically detects and uses the value of this environment variable.
Alternatively, you can provide your API key explicitly when [initializing the client](workflows-sdk-python#client).
### 3. Initialize the client and trigger a run
**Python**
The following code demonstrates initializing the SDK client, triggering a task run, and waiting for the run to complete. See below for more details.
```python:basic_task_runner.py
from render_sdk.client import Client
import asyncio
async def run_task():
# Initialize the client
client = Client()
# Kick off a task run
started_run = await client.workflows.run_task(
task_identifier="my-workflow/calculate-square",
input_data=[2]
)
print(f"Task run started: {started_run.id}")
print(f"Initial status: {started_run.status}")
# Wait for run to complete
finished_run = await started_run
print(f"Task run completed: {finished_run.id}")
print(f"Final status: {finished_run.status}")
if __name__ == "__main__":
asyncio.run(run_task())
```
You trigger a task run by calling the client's [`workflows.run_task`](workflows-sdk-python#workflows-run-task) method. This method takes the following arguments:
| Argument | Description |
|--------|--------|
| `task_identifier` | The **slug** indicating the task to run, available from your task's page in the [Render Dashboard][dboard]: [img] Every task slug has the following format: `{workflow-slug}/{task-name}` For example: `my-workflow/calculate-square` |
| `input_data` | A list containing the task's input arguments. Each element maps to the task's corresponding positional argument. The `calculate-square` task in the example above takes a single integer argument. For tasks that take zero arguments, provide an empty list, `[]`. |
The `workflows.run_task` method returns an [`AwaitableTaskRun`](workflows-sdk-python#the-awaitabletaskrun-class) object as soon as the run is created. This object provides the run's `id` and initial `status`, which are both available immediately. You can `await` this object to wait for the run to complete, at which point all other properties are available.
For full options and details, see the [Python SDK reference](workflows-sdk-python#workflows-run-task).
## Running with the Render API
The [Render API](api) provides an endpoint for triggering task runs, along with a variety of endpoints for retrieving workflow and task run details. The Workflows SDK uses the Render API behind the scenes, and you can also use it directly from your own code.
Start a task run by sending a POST request to the [Run a Task](https://api-docs.render.com/reference/createtask/) endpoint. The JSON body for this request includes two properties:
```json
{
"task": "my-workflow/calculate-square",
"input": [2]
}
```
| Property | Description |
|--------|--------|
| `task` | **Required.** An identifier specifying the task to run. You can provide either of two identifiers, both of which are available from your task's page in the [Render Dashboard][dboard]: [img] - The task's **slug** - This has the format `{workflow-slug}/{task-name}` (for example, `my-workflow/calculate-square`) - The task's **ID** - This has the format `tsk-abc123...` |
| `input` | **Required.** A list containing values for the task's [input arguments.](workflows-defining#task-arguments) For a task that takes zero arguments, provide an empty list, `[]`. |
## Running manually
You can manually trigger task runs directly from the Render Dashboard and CLI. This is handy for testing and debugging new tasks.
**Dashboard**
#### Running tasks manually in the Render Dashboard
1. From your workflow's **Tasks** page in the [Render Dashboard][dboard], click a task to open its **Runs** page.
2. Click **Run Task** in the top-right corner of the page:
[img]
A dialog appears for providing the task's input arguments:
[img]
3. Provide the task's input arguments as a JSON array. Each array element maps to the task's corresponding positional argument.
For example, you can provide `[5]` for a task that takes a single integer argument, or `[]` for a task that takes zero arguments.
You can click **Format** and **Validate** to cleanly structure your input and confirm that it's valid JSON.
4. Click **Start task**.
Your new task run appears at the top of the **Runs** table.
**CLI**
#### Running manually with the Render CLI
1. Make sure your development machine has version 2.4.2 or later of the Render CLI:
```shell{outputLines:2}
render --version
render version 2.4.2
```
If it doesn't, [install the latest version](cli#setup).
2. Run the following command:
```shell
render ea tasks list
```
The CLI opens an interactive menu of all workflow tasks in your workspace:
[img]
3. Select a task and press **Enter**, then select the `run` command.
The CLI prompts you to provide the task's input arguments as a JSON array:
[img]
4. Provide your desired arguments (or `[]` for a task that takes zero arguments) and press **Enter**. The CLI kicks off your task with a request to the Render API and begins tailing its logs.
You can remain in this view to view live logs from your task run.
5. Press **Esc** to navigate back up to the list of commands for your task. This time select the `runs` command.
The CLI opens an interactive menu of the task's runs:
[img]
6. Select a run and press **Enter**, then select the `results` command.
The CLI opens a view of the run's results:
[img]
# Local Dev with Render Workflows
> *[Render Workflows](workflows) are in limited early access.*
>
> During the early access period, the Workflows API and Python SDK might introduce breaking changes.
You can run workflow tasks on your local machine to iterate on them quickly. The Render CLI supports spinning up a *local task server* that simulates the entire task execution lifecycle. You can trigger task runs from your application code, or from the CLI itself.
As you iterate on your task definitions, the local task server picks up changes automatically. It also retains in-memory logs and results for each run (these are lost on server shutdown).
## Prerequisites
*Your development machine must have:*
- The Render CLI version 2.4.2 or later
- [Install the Render CLI](cli#setup)
- A workflow project repo that defines and registers tasks
- [Create your first workflow](workflows-tutorial)
## Starting the task server
From your workflow project repo, run the following command:
```shell
render ea tasks dev -- 
*Render [web services](web-services) can accept inbound WebSocket connections from the public internet.* Additionally, service types besides [static sites](static-sites) can initiate _outbound_ WebSocket connections over both the public internet and your [private network](private-network).
## Web service setup
In your web service code, you usually extend your existing HTTP server framework with WebSocket support. For example, in Node.js it's common to use the `ws` module with the Express framework to enable WebSocket connections.
See basic examples for some popular frameworks below, and consult your framework's documentation for additional details.
**Express (Node.js)**
This example uses Express along with the `ws` module:
```js:app.js
const express = require('express')
const { createServer } = require('http')
const WebSocket = require('ws')
const app = express()
const server = createServer(app)
const port = process.env.PORT || 10000
// Serves WebSocket connections at /ws (any path is fine)
const wss = new WebSocket.Server({ server, path: '/ws' })
// HTTP routes
app.get('/', (req, res) => {
res.send('Hello over HTTP!')
})
// WebSocket connections
wss.on('connection', (ws) => {
console.log('WebSocket client connected')
ws.on('message', (message) => {
console.log('Received:', message.toString())
ws.send(`Hello over WebSocket!`)
})
})
server.listen(port, () => {
console.log(`Server listening on port ${port}`)
})
```
**FastAPI (Python)**
This example uses FastAPI's built-in WebSocket support:
```python:main.py
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
app = FastAPI()
# HTTP routes
@app.get("/")
async def root():
return {"message": "Hello over HTTP!"}
# Serves WebSocket connections at /ws (any path is fine)
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
await websocket.accept()
logger.info("WebSocket client connected")
try:
while True:
data = await websocket.receive_text()
logger.info(f"Received: {data}")
await websocket.send_text(f"Hello over WebSocket!")
except WebSocketDisconnect:
logger.info("Client disconnected")
```
**Django (Python)**
This example uses the Django [Channels](https://channels.readthedocs.io/) framework. Note that you'll need to run your Django app with an ASGI-compatible server like [Daphne](https://github.com/django/daphne) or [Uvicorn](https://www.uvicorn.org/).
```python:routing.py
from django.urls import path
from . import consumers
# Serves WebSocket connections at /ws (any path is fine)
websocket_urlpatterns = [
path("ws", consumers.ExampleConsumer.as_asgi()),
]
```
```python:consumers.py
from channels.generic.websocket import AsyncWebsocketConsumer
import json
class ExampleConsumer(AsyncWebsocketConsumer):
# Called when a client connects
async def connect(self):
await self.accept()
# Called when a message is received from the client
async def receive(self, text_data):
# Send response back to this specific client
await self.send(text_data=json.dumps({
"message": "Hello over WebSocket!"
}))
async def disconnect(self, close_code):
# Cleanup when client disconnects
pass
```
**Rails (Ruby)**
This example uses the Rails [Action Cable](https://guides.rubyonrails.org/action_cable_overview.html) framework:
```ruby:app/channels/example_channel.rb
class ExampleChannel < ApplicationCable::Channel
# Called when a client connects
def subscribed
# Channel is ready to receive messages
end
# Called when a message is received from the client
def receive(data)
# Send response back to this specific client
transmit({ message: "Hello over WebSocket!" })
end
def unsubscribed
# Cleanup when client disconnects
end
end
```
Action Cable serves WebSocket connections at `/cable` by default.
## Connecting from clients
After you deploy WebSocket capabilities to your web service, you can start initiating connections from client code.
To test quickly, you can install the [`websocat`](https://github.com/vi/websocat) command-line tool to connect directly from your terminal:
```shell{outputLines:2,4-5}
brew install websocat
websocat wss://example-app.onrender.com/ws
test test
Hello over WebSocket!
```
> **Always use the `wss` protocol for WebSocket connections over the public internet.**
>
> If you use `ws`, most WebSocket clients fail when Render responds to their "handshake" request with a 301 code (attempting to redirect to TLS).
>
> For local server testing and connections over your [private network](private-network), use `ws`.
Here's a simple Node.js client that connects to a Render-hosted WebSocket server:
```js:client.js
const WebSocket = require('ws')
const ws = new WebSocket('wss://example-app.onrender.com/ws') // highlight-line
ws.onopen = () => {
ws.send('Hello from the client!')
}
ws.onmessage = (event) => {
console.log('Received:', event.data)
}
```
Regardless of your language or framework, all you need to do is specify your web service's public URL ([custom domains](custom-domains) work great), including the path for your WebSocket server.
## Maintaining connections
Render does not enforce a maximum duration for WebSocket connections. However, a variety of factors can cause a connection to be interrupted (instance shutdowns, network issues, platform maintenance, and so on).
To maintain active connections and detect stale ones, your web service and its connected clients should periodically send each other keepalive messages. The [WebSocket protocol](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2) defines special `ping` and `pong` control frames specifically for this purpose. When one side sends a `ping`, the other side should respond with a `pong`:
Many WebSocket libraries automatically handle `pong` responses, so you usually only need to implement `ping` logic on each side.
### Server-side pings
On the server side, periodic pings help you detect stale connections as early as possible. This helps you free up resources to maintain performance.
The example below extends the earlier [Express example](#web-service-setup) to add a basic "heartbeat" using `ping`. The same concepts apply to other languages and frameworks.
2. Click on the *MANAGE* button on the right and select the *Advanced DNS* tab. 3. Remove any existing `A` records for `@` and click on `Add New Record`. Add an `A` record for host `@` pointing to Render's load balancer IP `216.24.57.1`. We recommend setting the TTL to 1 minute so we can verify the domain faster. [img]
4. Remove any existing `CNAME` or Redirect records for `www` and click on `Add New Record`. Add a `CNAME` record for host `www` pointing to your Render subdomain which looks like `example.onrender.com`. Again, set the TTL to 1 minute. [img]
The final configuration should look something like this: [img] That's it! DNS changes can take a few minutes to propagate, but once they do you should be all set. # Configuring DNS Providers > This guide assumes you've added a custom domain to your service in the Render Dashboard. If you haven't yet, first complete [this step](custom-domains#1-add-your-domain-in-the-render-dashboard). This article explains how to configure your DNS provider to point your [custom domain](custom-domains) to Render. Some of these steps might not apply to your provider. We have specific guides for popular DNS providers: - [Configuring Cloudflare DNS](configure-cloudflare-dns) - [Configuring Namecheap DNS](configure-namecheap-dns) We're also happy to help you set things up—just contact us via the Help link in the dashboard. > *Remove any `AAAA` records from your domain while configuring DNS.* > > `AAAA` records map to an IPv6 address, and Render uses IPv4. These records can cause unexpected behavior for your custom domain. ## Configuring root domains ### Using an `ANAME` or `ALIAS` record When you're pointing a root domain like `example.com` to your Render subdomain, you can use `ANAME` or `ALIAS` records if your DNS provider supports them. These records are not part of the standard DNS protocol but are implemented by some providers to make it easy to point root domains to other domains. [DNSimple](https://dnsimple.com/), [DNS Made Easy](https://dnsmadeeasy.com/), [Name.com](https://www.name.com/) and [NS1](https://ns1.com/) all support one or both of these record types. - `ANAME` records let you refer to other domains just like `CNAME` records, but behave like `A` records in that they ultimately resolve to an IP address. This is also often called [CNAME flattening](https://support.cloudflare.com/hc/en-us/articles/200169056-Understand-and-configure-CNAME-Flattening). Read more [here](https://dnsmadeeasy.com/services/anamerecords/). - `ALIAS` records map a root domain to another domain while coexisting with other record types for the root domain. Read more [here](https://support.dnsimple.com/articles/alias-record/). To configure your custom root domain for Render, add an `ANAME` or `ALIAS` record for your root domain to point to your app's Render subdomain. For example, if your app subdomain is `example.onrender.com` and your custom domain is `example.com`, you should add an `ANAME` or `ALIAS` record for `example.com` and point it to `example.onrender.com`. ### Using an `A` record If your DNS provider does not support `ANAME` or `ALIAS` records or `CNAME` flattening, you will need to add an `A` record to point to your Render app. `A` records point to IP addresses, and you can use `216.24.57.1` to point your root domain to Render's load balancer IP. Once you have made changes to your DNS records, these need to propagate across the internet - this can delay the verification process. Use the `dig` command or an online service like [dnschecker](https://dnschecker.org/) to verify the correct response. If you see additional values in the DNS response other than those provided by Render, your DNS provider may have some defaults or features (e.g., domain forwarding) that need to be removed/disabled. > If you are using Cloudflare as a DNS provider, you must use a CNAME record instead of an A record. See configuring Cloudflare DNS for instructions. ## Configuring `www` and other subdomains For non-root domains, you should always add a `CNAME` record pointing to your app's Render subdomain. For example, if your Render subdomain is `example.onrender.com` and your custom domain is `www.example.com`, you should add a CNAME record for `www` and point it to `example.onrender.com`. # Outbound IP Addresses > *Outbound IPs were recently updated to use new ranges for each region.* > > [See details.](#changes-to-outbound-ips) Render services send outbound traffic through specific sets of IP ranges depending on their [region](regions). You can use these ranges to connect your service to IP-restricted environments outside of Render. Each IP range uses [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). As an example, the range `216.24.60.0/24` represents the IP addresses from `216.24.60.0` to `216.24.60.255`, inclusive. Your service might use _any_ IP address within its associated ranges. Outbound IP ranges are shared across _all_ services in the same region. > *Interested in unique, Render-native static IPs for your workspace?* > > - Please upvote [this feature request](https://feedback.render.com/features/p/exclusive-not-shared-static-outbound-ips). > - To ensure unique outbound IPs at this time, you can configure a static IP provider like [QuotaGuard](quotaguard). ## Obtaining your outbound IPs *To obtain a service's outbound IP ranges:* 1. Open the [Render Dashboard][dboard]. 2. Click a service to open its details page. 3. Open the *Connect* dropdown in the upper right. 4. Switch to the *Outbound* tab. Copy the list of IP ranges: [img] *Don't see the Outbound tab?* - Make sure you're viewing the details page for a particular service, not your workspace home. - Note that [static sites](static-sites) don't use outbound IP addresses, because they can't initiate outbound traffic. - If you created your workspace before *January 23, 2022*, [see below](#exception-for-some-oregon-services). ### Exception for some Oregon services *For workspaces created before January 23, 2022,* services in the Oregon [region](regions) do _not_ use a fixed set of outbound IP addresses. This remains the case after recent [changes to outbound IPs](#changes-to-outbound-ips). You can configure outbound IP addresses for these Oregon-region services in one of the following ways: - Configure a static IP provider like [QuotaGuard](quotaguard). - Create a _new_ workspace, then create replacement Oregon-region services in that workspace. Migrate over any data, domains, and configuration. ## Changes to outbound IPs On *November 13, 2025*, Render completed a migration to new outbound IP ranges for each [region](regions). Prior the migration, each region used a different, fixed set of individual IP addresses. Those individual addresses are now retired. If you use your service's outbound IPs to authorize access to an external system, make sure to add the new IP ranges to that system's access rules: 1. Open your service's settings in the [Render Dashboard][dboard] and click the *Connect* dropdown in the upper right. 2. Switch to the *Outbound* tab to view your service's new IP ranges: [img] *Don't see the Outbound tab?* - Make sure you're viewing the details page for a particular service, not your workspace home. - Note that [static sites](static-sites) don't use outbound IP addresses, because they can't initiate outbound traffic. - If you created your workspace before *January 23, 2022*, [see above](#exception-for-some-oregon-services). 3. Configure your external system to allow traffic from the listed ranges. Your service might connect from any address within these ranges. 4. If your external system allows connections from any of Render's original IP addresses, you can safely remove those addresses from your access rules. ## FAQ ###### What if my external system doesn't support allowlisting an entire CIDR range? To limit your service's outbound traffic to a smaller number of IP addresses, you can configure a static IP provider like [QuotaGuard](quotaguard). If you do, your service's outbound traffic will flow through your provider-managed IP(s), which you can then allow in your external system. > *Interested in unique, Render-native static IPs for your workspace?* > > Please upvote [this feature request](https://feedback.render.com/features/p/exclusive-not-shared-static-outbound-ips). # Inbound IP Rules You can configure which IP addresses can connect to your Render services over the public internet: [img] By setting these inbound IP rules, you can grant access only to IP ranges you trust. *All workspaces* can set inbound IP rules for: - Individual [Render Postgres](postgresql-creating-connecting#restricting-external-access) and [Key Value](key-value#enabling-external-connections) datastores *Enterprise orgs* can also set rules for: - Individual web services and static sites - An entire [environment](projects) - An entire workspace After you set IP rules, Render only allows inbound service connections from the IP ranges you specify. Disallowed IPs are automatically blocked with a `403 Forbidden` response. Requests are blocked at the edge and do not reach your service. For web services, blocked requests _do_ still appear in [HTTP request logs](logging#http-request-logs). > *Inbound IP rules apply only to connections from the public internet.* > > These rules do not apply to inter-service communication over your [private network](private-network). For private network controls, see [Blocking cross-environment traffic](projects#blocking-cross-environment-traffic). ## Setup ### Render Postgres / Key Value All workspaces can set inbound IP rules for Render Postgres and Key Value. See the documentation for each type of managed datastore: - [Render Postgres](postgresql-creating-connecting#restricting-external-access) - [Render Key Value](key-value#enabling-external-connections) ### All other resource types > *Setting IP rules for any resource besides a [managed datastore](#render-postgres--key-value) requires an Enterprise org.* Follow these steps to set inbound IP rules for a web service, static site, environment, or workspace. 1. In the [Render Dashboard][dboard], open the settings page for the service or environment you want to configure. - For workspace-level rules, click *Network Access* in the left pane of your workspace home. 2. Scroll down to the *Networking* section and find *Inbound IP Restrictions*: [img] If you haven't made any changes yet, you'll see a single default rule: `0.0.0.0/0` (allow all IPs). 3. Click an existing rule to edit it, or click *+ Add source* to create a new rule. You can also click the trash icon next to a rule to delete it. - Learn more about [rule format](#rule-format) below. > *If you delete all rules, Render blocks _all_ inbound traffic to the affected service(s)!* 4. Click *Save* to apply your changes. You're all set! Your new rules take effect within a few seconds. ## Rule format Inbound IP rules are allowlists of IP ranges you specify using [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). Render allows connections from the IP ranges you specify and blocks connections from all other IPs. > *Only IPv4 CIDR ranges are supported.* Here are some example ranges: | Rule | Meaning | |--------|--------| | `0.0.0.0/0` | Allow any IP address. This is the default rule for services besides [Render Key Value instances.](key-value#enabling-external-connections) | | `203.0.113.0/24` | Allow IP addresses `203.0.113.0` through `203.0.113.255`. This might represent a company's office network or a trusted third-party service. | | `198.51.100.16/29` | Allow IP addresses `198.51.100.16` through `198.51.100.23`. This smaller range of 8 addresses might represent a specific subnet of an office network. | | `203.0.113.42/32` | Allow _only_ the IP address `203.0.113.42`. The `/32` suffix limits the rule to the single defined IP address. This is useful for allowing only your own development machine. | ## Combining IP rules > *This section applies only to Enterprise orgs.* When a service is subject to IP rules at multiple levels (workspace, environment, and/or service), an inbound IP must be allowed by _each level's_ rules to successfully connect:
If an IP is allowed at the service level but disallowed at the environment level (or vice versa), the connection is blocked.
When you view a service's inbound IP rules, you can see each level of rules that apply to it:
[img]
## FAQ
###### Can I set IP rules for a private service / background worker / cron job?
No. These service types never receive traffic from the public internet.
###### How do I allow connections from all IP addresses?
Include the value `0.0.0.0/0` (CIDR notation for "any IPv4 address") in your inbound IP rules.
This is the default rule for services besides [Render Key Value instances.](key-value#enabling-external-connections)
###### What happens if I delete all rules for a given resource?
If you delete all inbound IP rules for a given service, environment, or workspace, Render blocks _all_ inbound traffic to the affected service(s).
###### Why don't I see inbound IP rule settings for my web service?
Inbound IP rules require an [Enterprise org](enterprise-orgs) for everything besides [managed datastores.](#render-postgres--key-value)
# The Render Dashboard
The Render Dashboard is the web interface for managing everything in your Render workspace—services, team members, billing, and more:
[img]
Your dashboard's main page lists the services in your workspace, along with any [projects](projects) you've organized them into. Click any service to view its details, logs, and settings.
Use the left panel to jump to views for your [Blueprints](infrastructure-as-code) and [environment groups](configure-environment-variables#environment-groups).
This article describes some common dashboard actions to get you up and running. *_Most_ dashboard actions are documented in the article for the corresponding feature.*
> You can also manage Render resources from your terminal with the [Render CLI](cli) or programmatically with the [Render API](api).
## Create a new service
Create a new service by clicking the *+ New* button in the top-right corner of the [Render Dashboard][dboard]:
[img]
Select a service type from the list and complete the creation flow to deploy your code.
> *Deploying for the first time?* See our [quickstarts](#quickstarts).
## Create a workspace
See [Workspaces, Members, and Roles](team-members).
## Navigating the dashboard
Open workspace-wide search with `⌘+K` / `CTRL+K`, then use the arrow keys to jump directly to any resource:
[img]
While viewing a resource, use the breadcrumbs at the top of the page to navigate to a different service, environment, or project:
[img]
Switch workspaces using the dropdown at the top of the left pane:
[img]
## Manage billing
From your workspace's homepage in the [Render Dashboard][dboard] click *Billing* in the left pane:
[img]
*From this page, you can:*
- View and update your plan
- Update your payment method
- View accrued usage charges for the current billing month
- View invoices for past months
- View usage against your monthly included amounts of:
- [Free instance hours](free#free-instance-hours)
- [Outbound bandwidth](outbound-bandwidth)
- [Build pipeline minutes](build-pipeline#pipeline-minutes)
## Set your display theme
The Render Dashboard provides light and dark display themes, along with high-contrast variants of each.
To set your display theme:
1. Open the account menu in the top-right corner of the [Render Dashboard][dboard].
- *If you don't need to toggle high contrast,* click *Theme* to set your display theme and you're all set:
[img]
When you change your theme this way, Render keeps your current high contrast setting.
2. *If you _do_ need to toggle high contrast,* instead click *Account settings*.
3. Scroll down to the *Appearance* section:
[img]
4. Click *Edit* to switch between *Light*, *Dark*, and *System* (which follows your operating system's theme).
5. Click *Save changes*.
6. Separately, use the toggle to enable or disable *High Contrast Mode*.
## Add a user image
If you have a [Gravatar](https://gravatar.com/) account associated with your Render account's email address, your Gravatar image appears next to your email address in the top-right corner of the dashboard. Otherwise, a generic user icon is shown.
# SSH and Shell Access
You can initiate a shell session to your Render service from its *Shell* page in the [Render Dashboard][dboard]:
[img]
If your service is [scaled](scaling) to multiple instances, you can connect to a specific instance using the *Instance* dropdown.
You can also SSH into your services from the terminal after [completing setup](#ssh-setup).
## Compatible service types
Support for shell access varies by service type:
| Service type | Dashboard shell | SSH |
|--------|--------|--------|
| *Paid [web service](web-services)* | 🟢 | 🟢 |
| *[Private service](private-services)* | 🟢 | 🟢 |
| *[Background worker](background-workers)* | 🟢 | 🟢 |
| *[Cron job](cronjobs)* | 🟨 [See details.](#cron-job-connections) | ❌ |
| *[Free](free) web service* | ❌ | ❌ |
| *Other service types (static sites, datastores)* | ❌ | ❌ |
## SSH setup
### 1. Generate an SSH key pair
> *Skip this step if you already have an SSH key on your machine that you want to use.*
1. Run the following command to generate an Ed25519 key pair in the `~/.ssh` directory:
```shell
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
```
You can optionally use a different [key type](#supported-key-types).
2. The command prompts you to provide an optional passphrase for your private key (recommended for added security).
3. The command generates two files in your `~/.ssh` directory:
- `~/.ssh/id_ed25519` (private key)
- `~/.ssh/id_ed25519.pub` (public key)
> **Your private key is a secret credential. Don't share it with anyone.**
>
> To enable SSH access, you'll share the _public_ key with Render.
### 2. Add your public key to your Render account
1. Open your [Account settings page](http://dashboard.render.com/settings#ssh-public-keys) in the Render Dashboard.
2. Find the **SSH Public Keys** section and click **+ Add SSH Public Key**. The creation dialog appears.
3. Provide a descriptive **Name** for the key (e.g., "Personal Laptop").
4. Copy the full contents of your _public_ key file (ends in `.pub`) to your clipboard.
On macOS, you can use the `pbcopy` command to copy the file to your clipboard:
```shell
pbcopy < ~/.ssh/id_ed25519.pub
```
5. Paste your public key into the **Key** field:
[img]
6. Click **Add SSH Public Key** button to save your key.
All set! You're ready to [start an SSH session](#starting-an-ssh-session).
## Starting an SSH session
> **SSHing into a Docker-based service?** See [Docker-specific configuration](#docker-specific-configuration).
After completing [SSH setup](#ssh-setup), you can start SSH sessions from your terminal using the [Render CLI](cli), or by running the `ssh` command directly.
Select a method from the tabs below:
**Render CLI**
1. [Install and log in to the Render CLI](cli#setup) if you haven't already.
2. Run the following command:
```shell
render ssh
```
This opens an interactive menu that lists your workspace's SSH-compatible services.
3. Use the arrow keys to select a service and press **Enter**. The interactive menu closes and the SSH session starts.
To skip menu-based selection, you can include your service's ID directly in the `render ssh` command:
```shell
render ssh srv-abc123
```
**SSH command**
1. In the [Render Dashboard][dboard], open the settings for the service you want to connect to.
2. Click the **Connect** dropdown in the upper right and select the **SSH** tab:
[img]
> **Don't see the SSH tab?** The selected service is not SSH-compatible. See [Compatible service types](#compatible-service-types).
3. Copy the SSH command to your clipboard.
4. Paste the SSH command into your terminal and run it.
```shell
ssh YOUR_SERVICE@ssh.YOUR_REGION.render.com
```
5. You might see a warning like this:
```
The authenticity of host 'render.com (IP_ADDRESS)' can't be established.
ED25519 key fingerprint is (SSH_KEY_FINGERPRINT)
Are you sure you want to continue connecting (yes/no)?
```
If you do, confirm that the fingerprint in the message matches Render’s
[public key fingerprint](#renders-public-key-fingerprints) for your region. If it does, type `yes` to continue.
6. If you receive a "permission denied" message, see [Troubleshooting permission failures](#troubleshooting-permission-failures).
### Connecting to a specific instance
By default, SSH sessions connect to a random running instance of your service. To connect to a _specific_ instance, include that instance's 5-character slug in the hostname of your SSH command:
```shell{outputLines:1,3-4}
# Random instance
ssh srv-abc123@ssh.oregon.render.com
# Specific instance
ssh srv-abc123-d4e5f@ssh.oregon.render.com
```
As shown above, you append the instance slug to the service's ID (separated by a hyphen) to form the complete hostname.
Instance slugs are visible in your service's [logs](logging) and [application metrics](service-metrics#cpu-and-memory-usage). You cannot SSH into an instance that is no longer running.
### Troubleshooting permission failures
If you receive a "Permission denied" error, Render rejected the incoming SSH session. Take the following steps first to troubleshoot this issue:
#### Confirm which SSH key you're using
Add the "verbose" flag (`-v`) to your SSH command to get more details about which key is being used:
```shell{outputLines:2-9}
ssh -v YOUR_SERVICE@ssh.YOUR_REGION.render.com
[...]
debug1: identity file /Users/YOUR_NAME/.ssh/id_ed25519 type 3
debug1: identity file /Users/YOUR_NAME/.ssh/id_ed25519-cert type -1
[...]
debug1: Next authentication method: publickey
debug1: Offering public key: /Users/YOUR_NAME/.ssh/id_ed25519
[...]
Permission denied (publickey).
```
#### Confirm which keys are attached to your Render account
1. List any keys you have loaded into the [ssh-agent](https://en.wikipedia.org/wiki/Ssh-agent).
```shell
ssh-add -l
```
This should should print out a long string of numbers and letters.
```
256 SHA256:SSH_KEY_FINGERPRINT YOUR_NAME@YOUR_HOST (ED25519)
```
2. Open your settings page in the [Dashboard](https://dashboard.render.com/) and find the list of SSH public keys.
3. Compare the list of SSH keys with the output from the `ssh-add` command.
If you don't see your public key listed, you can [add it to your account](#ssh-setup).
## Render's public key fingerprints
Public key fingerprints can be used to validate a connection to a remote server.
Render’s public SSH key fingerprints are as follows:
| Region | Fingerprint |
|--------|--------|
| |
| |
| **Virginia** | `SHA256:NCpSwboPnqL/Nvyy2Qc8Kgzpc3P/f3w5wDphhc+UZO0` |
| **Frankfurt** | `SHA256:dBRrCEA0tBkvaYLzzDw/mzaANw6nUJO961Zx806spZs` |
| **Singapore** | `SHA256:CUlRyv4TZ0vmHwmhsJkII/pz2cO4IgvR+ykqnRsOQFs` |
You can also directly add Render's public keys to your `$SSH_DIR/known_hosts` file. Render's full set of entries is as follows:
```bash
# RENDER PUBLIC KEYS
# ------------------
# Oregon
ssh.oregon.render.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFON8eay2FgHDBIVOLxWn/AWnsDJhCVvlY1igWEFoLD2
# Ohio
ssh.ohio.render.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINMjC1BfZQ3CYotN1/EqI48hvBpZ80zfgRdK8NpP58v1
# Virginia
ssh.virginia.render.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ6uO0jKQX9IjefnLz+pxTgfPhsPBhNuvxmvCFrxqxAM
# Frankfurt
ssh.frankfurt.render.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILg6kMvQOQjMREehk1wvBKsfe1I3+acRuS8cVSdLjinK
# Singapore
ssh.singapore.render.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGVcVcsy7RXA60ZyHs/OMS5aQj4YQy7Qn2nJCXHz4zLA
```
## Usage details
### Supported key types
Render supports the following key types:
- `ed25519`
- `ecdsa`
- `rsa`
Render also supports U2F/FIDO hardware authenticated keys like a YubiKey.
- `ed25519-sk`
- `ecdsa-sk`
### Docker-specific configuration
If your service runs a [Docker image](docker), additional configuration is required for it to accept SSH connections:
1. Make sure your image includes openSSH (`openssh-server`).
2. Make sure your Dockerfile creates a `~/.ssh` directory for the running user with the correct permissions (`chmod 0700`).
3. If the running user is not the root user, that user must have shell access.
- If your Dockerfile references a parent image, you will need to perform these steps in a Dockerfile that you control, making use of the `USER` instruction to change back to a root user and `usermod` (or equivalent) to modify the non-root user, like so:
```dockerfile
# Switch to root to modify user
USER root
RUN usermod -s /bin/bash myuser
# Switch back to non-root user
USER myuser
```
Additionally, some configurations are not supported:
- If your Dockerfile specifies a root user, the account cannot be locked. Use `usermod --unlock root` or `passwd -u root` to unlock the account.
- If your service uses a [persistent disk](disks), you must not mount it to the `$HOME` directory of the running user.
### Cron job connections
When you connect to a cron job from the Dashboard shell, Render spins up a new, temporary instance of the service and connects to it. This instance includes your cron job's latest build and configuration. It does _not_ automatically execute the cron job's command. After you close the shell session, Render deprovisions the instance.
It is not possible to connect to the actual cron job instances that run as part of your cron schedule.
### Automatic session closure
Render automatically closes a service's active SSH sessions in the following cases:
- The service is redeployed or restarted for any reason.
- Render is scheduled to perform maintenance on underlying infrastructure that enables SSH connections.
- In this case, Render gives existing connections one hour before automatically closing them.
For long-running commands, consider spinning up a [one-off job](one-off-jobs) instead of SSHing into an active instance.
### Memory usage
SSH and dashboard shell sessions use the same memory pool that's allocated for your service instance. Using SSH requires about 2 MB of memory, plus about 3 MB for each active session (not including memory used by processes executed during the session).
As an example, let's say we SSH into one service instance from two different computers to run bash. In this case, memory usage would look like this:
- 8 MB for SSH
- 2 MB for SSH access
- 2x3 MB for the two SSH sessions
- 7 MB for bash
- 2x3.5 MB for the two bash processes
Total memory usage in this case is about 15 MB.
# Projects and Environments
Render *projects* enable you to organize your services by application and environment:
[img]
For example, one of your applications might include a static site, a GraphQL backend, and a database. By adding all of these services to the same project, you can find and manage them more quickly.
Each project has one or more *environments* (such as *Production* in the screenshot above). If you run staging and production versions of your app, you can add each version's services to a different environment.
You can also set *[environment-specific controls](#environment-specific-controls):*
- [Define environment variables and secret files](#scoped-configuration) that only services in a single environment can access.
- Prevent your staging services from inadvertently using a production-specific credential (or vice versa).
- Designate an environment as [protected](#protected-environments) so that only your workspace's admins can make potentially destructive changes to its resources.
- [Block private network traffic](#blocking-cross-environment-traffic) from entering or exiting a specific environment.
- Prevent your staging services from inadvertently accessing a production database (or vice versa).
## Setup
> *Hobby workspaces can have up to one project with up to two environments.*
>
> To create additional projects or environments, [upgrade your workspace](team-members#change-a-workspaces-plan).
### Create a project
1. In the [Render Dashboard][dboard], click *New > Project*:
[img]
The following form appears:
[img]
2. Provide a name for your new project, along with a name for its first environment.
- Both of these names are for your own informational purposes. You can change them later.
3. Click *Create a project*.
That's it! You're redirected to the page for your new project.
### Add services to an environment
If an environment in your project is empty, it displays buttons for creating a new service or moving some of your workspace's existing services into the project:
[img]
You can specify a new service's associated project and environment during the creation flow.
You can bulk-move services to an environment by selecting them in your workspace's service list and then clicking *Move*:
[video]
You can also move an individual service by opening its *•••* menu and clicking *Move*.
### Open a project
Your workspace's homepage in the [Render Dashboard][dboard] lists all projects at the top:
[img]
Click a project to open it. Services belonging to a project appear on that project's page, _not_ on your workspace's homepage.
### Modify a project
- To add an environment to a project, click *+ Add environment* at the top right of the project's page.
- To configure an existing environment, click the *•••* menu at the top right of that environment's section on the project's page.
- To rename or delete an entire project, click *Settings* in the left pane of the project's page.
> *Important:*
>
> - Deleting a project deletes _all_ of its associated environments and services.
> - Deleting an environment deletes all of its associated services.
## Blueprint support
[Blueprints](infrastructure-as-code) (Render's infrastructure-as-code model) support creating projects and environments, along with assigning your resources to them:
```yaml
projects:
- name: my-project
environments:
- name: production
# These resources will belong to the my-project/production environment.
# Do not duplicate these definitions at the root level.
services:
- name: my-web-service
type: web
envVars:
- key: MY_ENV_VAR
value: my-value
databases:
- name: my-database
type: postgres
envVars:
- key: DATABASE_URL
fromDatabase:
name: my-database
property: connectionString
envVarGroups:
- name: my-env-group
envVars:
- key: MY_ENV_VAR
value: my-value
# Environment-specific settings
networking:
isolation: enabled
permissions:
protection: enabled
```
For details, see the [YAML reference](blueprint-spec#projects-and-environments).
## Environment-specific controls
### Scoped configuration
[Environment groups](configure-environment-variables#environment-groups) are a helpful way to share environment variables and/or secret files across multiple services in your workspace.
You can optionally scope an environment group to a single project environment. This helps you share configuration across multiple services in that environment, while also ensuring that services in _other_ environments _can't_ use that environment group.
Move an environment group into a project environment from the group's info page by clicking **Manage > Move group**:
[img]
After you move your environment group, it appears on the corresponding project's overview page:
[img]
### Protected environments
Workspace members with the [**Admin** role](team-members#member-roles) can designate any project environment as **protected**. This restricts other members from performing potentially destructive actions ([listed below](#restricted-actions)).
#### Steps to configure
1. Go to your project's page in the [Render Dashboard][dboard] and scroll to the environment you want to configure.
2. Click the **•••** menu at the top right of the environment, then click **All settings**.
3. Scroll down to the **Permissions** section and click **Edit**:
[img]
4. Select **Protected** and click **Save**.
Protected environments display a label and a lock icon on your project's page in the Render Dashboard:
[img]
#### Restricted actions
> **Important:** If your protected environment includes resources that are managed via [Blueprints](infrastructure-as-code), non-**Admin** workspace members _can_ still modify those resources by publishing an update to the corresponding `render.yaml` file.
Only **Admin** workspace members can perform the following actions in a protected environment:
**Resource management**
- Deleting any of the environment's resources (services, [environment groups](#scoped-configuration), etc.), or deleting the environment itself
- Creating new resources in the environment
- Moving resources into or out of the environment
**Operational controls**
- Modifying access control IPs for any Render Postgres or Key Value instance in the environment
- Suspending or resuming any service in the environment
- Toggling [maintenance mode](maintenance-mode) for any service in the environment
- Accessing the shell for any service in the environment
**Secret values**
- Viewing or modifying environment variables or secret files for any service or environment group in the environment
- Viewing passwords or connection URLs for any Render Postgres or Key Value instance in the environment
### Blocking cross-environment traffic
By default, all of your Render services in the same region can communicate over their shared [private network](private-network).
You can configure an environment to _block_ private network traffic from crossing its boundary. If you do, services _within_ the environment can still communicate:
[diagram]
This helps you prevent your staging services from inadvertently accessing a production resource (or vice versa).
> **This setting only affects _private network_ traffic.**
>
> - Web services and static sites in the environment can still receive public internet traffic at their `onrender.com` subdomain, _including_ traffic originating from your services outside the environment.
> - Render Postgres and Key Value instances in the environment can still receive traffic at their external URL from [allowed IPs](postgresql-creating-connecting#restricting-external-access).
> - Workspace members can still access services in the environment over [SSH](ssh).
> - In a [protected environment](#protected-environments), only **Admin** workspace members can access the shell for services in the environment.
#### Steps to configure
> Toggling this feature does not trigger any deploys or cause any interruptions for your running services.
1. Go to your project's page in the [Render Dashboard][dboard] and scroll to the environment you want to configure.
2. Click the **•••** menu at the top right of the environment, then toggle **Block cross-environment connections**:
[img]
> **Enabling this feature does not terminate any active network connections.**
>
> To ensure that all existing connections are terminated, you can restart your services in the environment.
You're all set! Your environment now blocks private network traffic from crossing its boundary.
### Environment-level IP rules
Enterprise orgs can set inbound IP rules for all services in a particular environment. These rules apply to inbound connections from the public internet.
For details, see [Inbound IP rules](inbound-ip-rules).
## FAQ
###### Does an environment named 'Production' or 'Staging' have special restrictions or capabilities?
**No.** Render does not apply special logic to any environment based on its name. The examples above use "Production" and "Staging" because they're common.
###### Will my service behave differently after I add it to a project?
**Possibly.** If you've configured any [environment-specific controls](#environment-specific-controls) for the service's corresponding environment, those controls apply to the service.
For example, if the service's environment [blocks cross-environment network traffic](#blocking-cross-environment-traffic), the service can no longer communicate over your private network with services outside the environment.
###### Can I use projects and environments with Blueprints (Render's infrastructure-as-code model)?
**Yes.** You can define projects and environments in your `render.yaml` file, then assign new and existing resources to them.
For details, see the [YAML reference](blueprint-spec#projects-and-environments).
###### Are preview environments tied to projects?
*No.* You manage your workspace's [preview environments](preview-environments) with [Blueprints](infrastructure-as-code), not projects. A preview environment can include services that belong to any number of different projects.
###### Can I use the same service name in multiple project environments?
*No.* All of a workspace's services must have unique names—even services that belong to different project environments.
# Scaling Render Services
You can run multiple instances of a [web service](web-services), [private service](private-services), or [background worker](background-workers) to handle additional load. For services that receive incoming traffic, Render load balances that traffic evenly across all running instances:
[diagram]
Each instance of a scaled service uses the same instance type and is [billed accordingly](#billing-for-scaled-services). You can scale each service up to a maximum of 100 instances.
Render supports two scaling methods: *manual scaling* and *autoscaling*.
| Scaling Method | Description |
|--------|--------|
| [*Manual scaling*](#manual-scaling) | Render runs a fixed number of instances that you specify. Manual scaling is available for all Render workspaces. |
| [*Autoscaling*](#autoscaling) | *Available only for [Professional workspaces](professional-features) and higher.* Render automatically scales your number of instances between a specified minimum and maximum, based on target CPU and/or memory utilization. |
## Manual scaling
You can manually scale your service to any fixed number of instances, up to a maximum of 100.
1. In the [Render Dashboard][dboard], open your service's *Scaling* page and scroll down to the *Manual Scaling* section:
[img]
2. Drag the slider to the desired number of instances, or enter a value between `1` and `100` in the text box.
3. Click *Save Changes*.
Render immediately provisions or deprovisions instances as needed to match the new instance count.
Manual scaling events appear in the timeline on your service's *Events* page:
[img]
## Autoscaling
> *Autoscaling requires a [*Professional workspace*](professional-features) or higher.*
Render can automatically scale your service up and down based on CPU and/or memory utilization targets that you specify. This helps you handle periods of high traffic while also minimizing compute costs.
Enable autoscaling for your service from its *Scaling* page in the [Render Dashboard][dboard]:
[img]
1. Use the slider to set your desired minimum and maximum instance count, or enter a value in each text box.
- Render always keeps your instance count within the specified range, even if resource utilization is significantly below or above your specified target.
2. Scroll down to set your target CPU and/or memory utilization:
[img]
Enable one or both of the toggles and set your target utilization percentage(s).
> If you enable _neither_ toggle, autoscaling is _disabled_ for the service.
3. Click *Save Changes*.
Render begins monitoring resource utilization and automatically scales your service up or down as needed based on your specified targets.
Autoscaling events appear in the timeline on your service's *Events* page:
[img]
### How autoscaling works
Render periodically calculates average resource utilization across all instances of your autoscaled service. Using that value (`current_util`), Render determines whether to scale your service based on the following formula:
```
new_instances = ceil[current_instances * (current_util / target_util)]
```
If `new_instances` doesn't equal `current_instances`, Render scales your service up or down to the new instance count.
> **Render waits a few minutes before scaling a service _down_.**
>
> If utilization rises again during this period, Render does _not_ scale the service down. This minimizes unnecessary scaling actions during periods of "spiky" usage.
>
> Render always scales a service _up_ immediately to handle increased load.
#### Example 1: Scaling up
| Current instances | Current CPU | Target CPU |
| ----------------- | ----------- | ---------- |
| 2 | 80% | 60% |
```
new_instances = ceil[2 * (80% / 60%)] = 3
```
In this scenario, Render immediately scales the service up from 2 instances to 3.
#### Example 2: Scaling down
| Current instances | Current Memory | Target Memory |
| ----------------- | -------------- | ------------- |
| 5 | 20% | 60% |
```
new_instances = ceil[5 * (20% / 60%)] = 2
```
In this scenario, Render waits a few minutes, then scales the service down from 5 instances to 2 if memory utilization remains low.
> If you set targets for both CPU _and_ memory utilization, Render calculates `new_instances` based on each and uses the larger result.
## Billing for scaled services
Billing for a scaled service is based entirely on compute usage, which is prorated by the second. There is no additional cost for performing a scaling action.
Here are some example scenarios:
| Scenario | Billing Result |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| You run exactly two instances of a service for an entire month. | You're billed for *2x* the monthly price of your service's instance type. |
| Exactly halfway through a month, you manually scale your service from two instances down to one. It remains at one instance for the rest of the month. | You're billed for *1.5x* the monthly price of your service's instance type. |
| Every day of a month, your service autoscales from one instance to two for exactly six hours. It then autoscales back down to one instance. | You're billed for *1.25x* the monthly price of your service's instance type. |
See your exact compute usage for the month on your [Billing page](https://dashboard.render.com/billing). You can also review your [invoice history](https://dashboard.render.com/billing#invoice-history).
## Application considerations
- Services with an attached [persistent disk](disks) _cannot_ scale to multiple instances.
- You can update your service's scaling configuration programmatically via the [Render API](api).
- Separate endpoints are available for [manual scaling](https://api-docs.render.com/reference/scale-service) and [autoscaling](https://api-docs.render.com/reference/autoscale-service).
- If you configure both manual scaling _and_ autoscaling for a service, Render enables autoscaling and ignores the manual scaling configuration.
## Horizontal vs. vertical scaling
The sections above describe Render's support for *horizontal scaling*, where you adjust a service's number of running instances.
In contrast, *vertical scaling* refers to adjusting a service's compute resources (RAM and CPU). You vertically scale a service by changing its instance type in the [Render Dashboard][dboard].
### When to use each
- *Scale horizontally* to handle a higher number of _simultaneous_ tasks (such as incoming requests).
- *Scale vertically* if each _single_ task requires additional RAM or CPU to run efficiently.
- For particularly resource-intensive tasks, consider offloading to a [background worker](background-workers) to keep your web services responsive.
*Horizontal scaling usually occurs much more frequently than vertical scaling.* Autoscaled services might change their instance count multiple times per day, whereas you might upgrade a service's instance type once in a year.
# Service Previews
Render *service previews* enable you to test out proposed changes to a web service or static site before you deploy those changes to production.
[img]
For each service preview, Render creates a _separate, temporary instance_ of your service with its own `onrender.com` URL (served over HTTP/2 with full TLS), so you can validate your changes safely. Render automatically sets the HTTP response header `X-Robots-Tag: noindex` for all preview instances.
There are two types of service previews:
- [*Pull request previews*](#pull-request-previews-git-backed) (for Git-backed services)
- [*Image previews*](#image-previews) (for services that deploy a Docker image from a container registry)
See details for each below.
> *Service previews only replicate the service with proposed changes.*
>
> To create temporary instances of _multiple_ services (including datastores) for integration testing, see [Preview Environments](preview-environments).
## Pull request previews (Git-backed)
For Git-backed services, Render can create a service preview for pull requests opened against your linked branch. You can create a separate preview for every pull request, or only for pull requests that you specify.
### Steps to enable
1. In the [Render Dashboard][dboard], select your service and open its *Previews* tab:
2. Under *Pull Request Previews*, select either *Manual* or *Automatic*:
[img]
For details on each option, see [Manual vs. automatic previews](#manual-vs-automatic-pr-previews).
That's it! After you enable service previews, active preview instances appear on your service's *Previews* tab:
[img]
Preview details also appear on their associated PR:
- *On GitHub,* preview instances are represented as deployments associated with your PR:
[img]
Click *View deployment* to open the preview instance in your browser.
- *On GitLab and Bitbucket,* Render adds a comment to your PR with a link to your preview instance.
### Manual vs. automatic PR previews
| Preview Mode | Description |
|--------|--------|
| *Manual* | By default, Render does _not_ create PR previews. To create a preview for a specific PR, do any of the following: - Add the label `render-preview` to the PR (GitHub/GitLab only). - Include the string `[render preview]` in your PR's _title_ (not the commit message). You can add or remove the above values from an existing PR at any time. If you do, Render creates or deprovisions the associated preview instance accordingly. |
| *Automatic* | By default, Render creates a preview instance for _every_ PR against your service's linked branch. To skip creating a preview for a specific PR, do any of the following: - Add the label `render-preview-skip` to the PR (GitHub/GitLab only). - Include any of the following strings in your PR's _title_ (not the commit message): - `[skip preview]` - `[preview skip]` - `[skip render]` - `[render skip]` You can add or remove the above values from an existing PR at any time. If you do, Render creates or deprovisions the associated preview instance accordingly.
> *Your pull request's title might be included in the message for its associated merge commit.* If you use `[skip render]` or `[render skip]`, this also [skips the auto-deploy](deploys#skipping-an-auto-deploy) for the service when merged. To avoid this, instead use `[skip preview]` or `[preview skip]`.
|
### Working with PR previews
- Preview instances copy all of their settings over from their base service when they're first created. *This includes environment variables, such as database connection information.*
> Make sure to change environment variables on your preview instance if you want it to use a staging or test database.
- Your app can detect whether it's a PR preview by checking the value of the `IS_PULL_REQUEST` environment variable (`true` for a PR preview, `false` otherwise).
- Whenever you push to the branch for an open PR, Render automatically updates the PR preview by building and deploying the latest commit.
- Render *automatically deletes* a PR preview instance when its associated PR is merged or closed.
- You can _manually_ delete a PR preview instance from its *Settings* tab in the [Render Dashboard][dboard]. However, Render _recreates_ the instance if you push new changes to the associated PR branch.
- If you're using a monorepo, you can fine-tune its PR preview behavior by [defining the root directory or specifying build filters](monorepo-support#using-with-service-previews).
- If you make changes to your base service after creating a PR preview, those changes are _not_ applied to the preview instance.
### Billing for PR previews
*PR Previews are billed at the same rate as your base service.* They are always prorated by the second.
- If your base service is a free static site, its PR previews are also free.
- If your base service costs \$25 per month and one of its PR preview instances is active for _half_ of a month, that preview instance costs a total of \$12.50.
## Image previews
For [image-backed services](deploying-an-image), you can create a service preview using the [Render API](api). Specifically, you use the [Create service preview](https://api-docs.render.com/reference/preview-service) endpoint:
```
POST https://api.render.com/v1/services/{serviceId}/preview
```
You can add this API request to your CI pipeline to automatically generate an image preview whenever an image tag is created or updated in your container registry. [See an example.](#example-github-action)
Preview instances can deploy any tag or digest for the base service's associated Docker image. For details, see the [API reference](https://api-docs.render.com/reference/preview-service).
You can view all active previews from your service's **Previews** tab in the [Render Dashboard][dboard]:
[img]
### Working with image previews
- Preview instances copy all of their settings over from their base service when they're first created. **This includes environment variables, such as database connection information.**
> Make sure to change environment variables on your preview instance if you want it to use a staging or test database.
- **Render does not automatically delete image previews.** Make sure to delete image previews when you're finished with them, either from the Render Dashboard or [via the Render API](https://api-docs.render.com/reference/delete-service).
- If you make changes to your base service after creating an image preview, those changes are _not_ applied to the preview instance.
### Billing for image previews
**An image preview is billed according to the instance type you specify in your API request.** If you don't specify an instance type, Render uses the same instance type as the base service.
> If your base service uses a paid instance type, its previews can't use the [Free instance type](free).
### Example GitHub Action
This example uses GitHub Actions and pushes images to Docker Hub, but the high-level steps apply to any combination of CI provider and container registry.
```yaml
# This GitHub Action demonstrates building a Docker image,
# pushing it to Docker Hub, and creating a Render build
# preview with every push to the main branch.
#
# This Action requires setting the following secrets:
#
# - DOCKERHUB_USERNAME
# - DOCKERHUB_ACCESS_TOKEN (create in Docker Hub)
# - RENDER_API_KEY (create from the Account Settings page)
# - RENDER_SERVICE_ID (the service to create a preview for)
#
# You must also set env.DOCKERHUB_REPOSITORY_URL below.
#
# Remember to delete previews when you're done with them!
# You can do this from the Render Dashboard or via the
# Render API.
name: Preview Docker Image on Render
# Fires whenever commits are pushed to the main branch
# (including when a PR is merged)
on:
push:
branches: ['main']
env:
# Replace with the URL for your image's repository
DOCKERHUB_REPOSITORY_URL: REPLACE_ME
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Check out the repo
uses: actions/checkout@v5
- name: Build the Docker image
run: docker build . --file Dockerfile --tag $DOCKERHUB_REPOSITORY_URL:$(date +%s)
- name: Log in to Docker Hub
uses: docker/login-action@v2.2.0
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_ACCESS_TOKEN }}
- name: Docker Metadata action
uses: docker/metadata-action@v4.6.0
id: meta
with:
images: ${{env.DOCKERHUB_REPOSITORY_URL}}
- name: Build and push Docker image
uses: docker/build-push-action@v4.1.1
id: build
with:
context: .
file: ./Dockerfile
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
- name: Create Render service preview
uses: fjogeleit/http-request-action@v1
with:
# Render API endpoint for creating a service preview
url: 'https://api.render.com/v1/services/${{ secrets.RENDER_SERVICE_ID }}/preview'
method: 'POST'
# All Render API requests require a valid API key.
bearerToken: ${{ secrets.RENDER_API_KEY }}
# Here we specify the digest of the image we just
# built. You can alternatively provide the image's
# tag (main) instead of a digest.
data: '{"imagePath": "${{ env.DOCKERHUB_REPOSITORY_URL }}@${{ steps.build.outputs.digest }}"}'
```
# Rollbacks
To revert undesired code changes as quickly as possible, you can *roll back* your service to a previous successful deploy. Render can reuse [build artifacts](#build-retention) from recent deploys, so rollbacks complete much faster than building a new version of your service.
## Triggering a rollback
**Dashboard**
1. In the [Render Dashboard][dboard], go to your service's *Events* page.
2. In the event list, find a recent successful deploy and click *Rollback*:
[img]
3. On the confirmation page, click *Rollback to this deploy*.
That's it! Render kicks off a _new_ deploy using the target deploy's build artifact.
**API**
To trigger a rollback via the Render API, use the [Roll back deploy](https://api-docs.render.com/reference/rollback-deploy) endpoint.
> *This endpoint does _not_ disable automatic deploys for the service.*
>
> This means that pushing a new commit to the service's linked branch will trigger a new deploy, which might reintroduce the undesired code change.
>
> You can disable automatic deploys for the service using the [Update service](https://api-docs.render.com/reference/update-service) endpoint. Set the `autoDeploy` parameter to `false`.
## Reenabling automatic deploys
Triggering a rollback in the Render Dashboard automatically disables [autodeploys](deploys#automatic-git-deploys) for the service. This safeguard prevents new changes from triggering a deploy that might reintroduce the undesired code change.
After you resolve the underlying issue, you can reenable automatic deploys from your service's *Settings* page:
[img]
> *Rolling back via the Render API does _not_ disable automatic deploys.*
>
> For details, see the *API* tab under [Triggering a rollback](#triggering-a-rollback).
## Build retention
Render retains a fixed number of recent build artifacts for each service, based on your [workspace plan](pricing). You can only roll back to a particular deploy if its build artifact is still available.
## What's rolled back?
### Service-specific config
When you roll back, Render reuses certain configuration details from the target deploy you selected. Other settings use the service's _current_ configuration.
> *Rolling back does not overwrite any of your service's current configuration settings.*
>
> Render reuses the target deploy's settings _only_ for the rollback. When you next trigger a _standard_ deploy, Render uses the service's current configuration as usual.
🟢 Matches the target deploy
❌ Uses the service's current configuration
🟨 Partially matches the target deploy (details provided)
| Configuration | Matches target deploy |
|--------|--------|
| Start command | 🟢 |
| [Health check path](deploys#health-checks) | 🟢 |
| Docker command | 🟢 |
| Registry-hosted Docker image | 🟨 [See details below.](#registry-hosted-docker-images) |
| Build artifact | 🟢 |
| Instance count | 🟢 |
| Environment variables | 🟢 |
| Environment groups | 🟨 [See details below.](#environment-groups) |
| Disks | ❌ Disks retain state between all deploys and cannot be rolled back. Separately from rolling back, you can [restore a disk snapshot](disks#disk-snapshots). |
| Instance type | ❌ If the target deploy requires a larger instance type, consider upgrading your instance type before triggering a rollback. |
| Custom domains | ❌ |
| Static site redirects and rewrites | ❌ |
| Static site headers | ❌ |
#### Registry-hosted Docker images
If your service pulls and deploys a [prebuilt Docker image](deploying-an-image) from a container registry, the rollback uses the same image tag or digest as the target deploy.
As part of the rollback, Render pulls the image again. This has the following implications:
- If the target deploy specified its image with a tag, Render pulls the _latest_ image associated with that tag. This image might differ from the one used in the target deploy.
- Unlike tags, digests always refer to the exact same image. Using a digest ensures that rollbacks behave more predictably.
- If the specified image is no longer available or reachable in the registry, the rollback fails.
#### Environment groups
[Environment groups](configure-environment-variables#environment-groups) enable sharing configuration across multiple services. Rolling back does _not_ modify any values in an environment group, because other services might also depend on those values.
However, rolling back might modify _which_ environment groups are applied to the service (specifically, if the target deploy used a different set of environment groups from the service's current configuration).
> *Note the following*:
>
> - Because rollbacks skip the build step, any recent changes to environment group variables are not reflected in the build artifact.
> - If the target deploy included an environment group that has since been deleted, the rollback proceeds without it.
### Platform-level config
Rolling back _does not_ revert any changes that Render has made to the underlying platform since the target deploy. For example, if Render has since updated the native runtime for your service's programming language, the rollback uses the updated runtime.
# Maintenance Mode
To help you make major infrastructure changes safely, you can enable *maintenance mode* for any paid web service:
[img]
A web service in maintenance mode remains up and running, but it's unreachable from the public internet. This helps you ensure that no user actions are in progress while you make changes.
> A web service in maintenance mode is still reachable over your [private network](private-network), and via [SSH](ssh).
## Steps to enable
> Maintenance mode is available only for paid [web services](web-services).
1. From your web service's *Settings* page in the [Render Dashboard][dboard], scroll down to the *Maintenance Mode* section:
[img]
2. Toggle the switch and confirm your action in the dialog that appears.
That's it! After you confirm, Render immediately enables maintenance mode for the service. You can disable it at any time by toggling the switch back.
## Response format
While your web service is in maintenance mode, Render responds to every incoming request with a `503 Service Unavailable` status code and your specified *maintenance page*:
- By default, Render displays [this maintenance page](https://maintenance-mode-example.onrender.com/).
- Set a custom maintenance page by specifying its URL in your service's maintenance mode settings.
- *This must _not_ be a URL of the service in maintenance mode.* We recommend providing the URL of a page on a [static site](static-sites).
- If your custom URL returns an error, Render responds with that error (not the default maintenance page).
# One-Off Jobs
Sometimes it's useful to spin up a short-lived process to run a specific task, such as asset compilation or a database migration. You can do this on Render by creating a *one-off job*.
A one-off job uses the same build artifact and configuration as one of your existing Render services (this is the job's *base service*). This means the job can execute any of the base service's defined scripts and access its environment variables.
> A one-off job cannot access its base service's [persistent disk](disks) (if it has one).
While a one-off job is running, it's billed at the per-second rate for its specified [instance type](#instance-type-ids).
## Running a one-off job
You create a one-off job with Render API's [Create job](https://api-docs.render.com/reference/post-job) endpoint.
> *New to the Render API?* [Get started.](api)
This example `curl` command creates a one-off job that runs the command `echo hi` and exits:
```bash
curl --request POST 'https://api.render.com/v1/services/YOUR_SERVICE_ID/jobs' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"startCommand": "echo hi"
}'
```
To try out this example, substitute your service ID and API key where indicated.
- Your service ID is available in the [Render Dashboard][dboard]. Navigate to your service's page and copy the ID from the URL in your browser.
- This value starts with `crn-` for cron jobs and `srv-` for other service types.
- Learn how to [create an API key](api#1-create-an-api-key).
The Create job endpoint requires a `startCommand` parameter, which specifies the command Render will run to start the job.
You can optionally specify a `planId` to use a different instance type from the job's base service. [See supported instance types](#instance-type-ids).
### Build and environment
On creation, a one-off job obtains the following values from its base service:
- The base service's most recent successful build artifact
- All of the base service's configured [environment variables](configure-environment-variables)
A job uses this "snapshot" of the base service for its own execution. If these values later change in the base service, existing jobs are not affected.
### Response format
If creation succeeds, the [Create job endpoint](https://api-docs.render.com/reference/post-job) returns a JSON object with the following fields:
```json
{
"id": "job-c3rfdgg6n88pa7t3a6ag",
"serviceId": "crn-c24q2tmcie6so2aq3n90",
"startCommand": "echo hi",
"planId": "plan-crn-002",
"createdAt": "2025-03-20T12:16:02.544199-04:00"
}
```
Next, you can [track the job's progress](#tracking-job-progress).
### Tracking job progress
You can track a one-off job's progress in the Render Dashboard or via the Render API. Logs generated by one-off jobs are also included in your workspace's [log stream](log-streams).
Select a tab for details:
**API**
You can poll for a job's status using the Render API's [Retrieve job](https://api-docs.render.com/reference/retrieve-job) endpoint:
```bash
curl --request GET 'https://api.render.com/v1/services/YOUR_SERVICE_ID/jobs/YOUR_JOB_ID' \
--header 'Authorization: Bearer YOUR_API_KEY'
```
This endpoint's response includes timestamps for when the job started and finished, along with its status:
```json
{
"id": "job-c3rfdgg6n88pa7t3a6ag",
"serviceId": "crn-c24q2tmcie6so2aq3n90",
"startCommand": "echo hi",
"planId": "plan-crn-002",
"createdAt": "2025-03-20T07:20:05.777035-07:00",
"startedAt": "2025-03-20T07:24:12.987032-07:00", // highlight-line
"finishedAt": "2025-03-20T07:27:14.234587-07:00", // highlight-line
"status": "succeeded" // highlight-line
}
```
You can also list a service's jobs (with optional filters) using the [List jobs](https://api-docs.render.com/reference/list-job) endpoint.
**Dashboard**
In the [Render Dashboard][dboard], you can view the details of current and past one-off jobs from your base service's **Jobs** page:
[img]
This page also displays the logs for recent job runs. Render retains logs for one-off jobs according to your workspace's [log retention period](logging#retention-period).
### Terminating a job
- A one-off job terminates whenever its specified `startCommand` exits. Render automatically deprovisions the job's instance.
- You can terminate a one-off job manually with the [Cancel running job](https://api-docs.render.com/reference/cancel-job) endpoint, or from the base service's **Jobs** page in the Render Dashboard.
- If a one-off job hasn't exited after 30 days, Render automatically terminates it.
- If you redeploy or suspend the base service of a running one-off job, the job is _not_ terminated. It continues running using its existing build artifact and configuration.
## Instance type IDs
By default, a one-off job uses the same instance type as its base service and is billed accordingly. You can use a different instance type by providing a `planId` parameter to the [Create job](https://api-docs.render.com/reference/post-job) endpoint. This is most commonly useful for running basic tasks on lower-cost compute.
See below for supported values of `planId` according to your base service's type:
### Cron jobs
These instance type IDs apply only to cron job services.
| Instance Type ID | Instance Type | Specs |
|--------|--------|--------|
| `plan-crn-003` | Starter | 512 MB RAM 0.5 CPU |
| `plan-crn-005` | Standard | 2 GB RAM 1 CPU |
| `plan-crn-007` | Pro | 4 GB RAM 2 CPU |
| `plan-crn-008` | Pro Plus | 8 GB RAM 4 CPU |
### All other service types
These service type IDs apply to web services, private services, and background workers.
| Instance Type ID | Instance Type | Specs |
|--------|--------|--------|
| `plan-srv-006` | Starter | 512 MB RAM 0.5 CPU |
| `plan-srv-008` | Standard | 2 GB RAM 1 CPU |
| `plan-srv-010` | Pro | 4 GB RAM 2 CPU |
| `plan-srv-011` | Pro Plus | 8 GB RAM 4 CPU |
| `plan-srv-013` | Pro Max | 16 GB RAM 4 CPU |
| `plan-srv-014` | Pro Ultra | 32 GB RAM 8 CPU |
# Render Blueprints (IaC)
*Blueprints* are Render's infrastructure-as-code (IaC) model for defining, deploying, and managing multiple resources with a single YAML file:
[diagram]
*Show example Blueprint*
```yaml
# This is a basic example Blueprint for a Django web service and
# the Render Postgres database it connects to.
services:
- type: web # A Python web service named django-app running on a free instance
plan: free
name: django-app
runtime: python
repo: https://github.com/render-examples/django.git
buildCommand: './build.sh'
startCommand: 'python -m gunicorn mysite.asgi:application -k uvicorn.workers.UvicornWorker'
envVars:
- key: DATABASE_URL # Sets DATABASE_URL to the connection string of the django-app-db database
fromDatabase:
name: django-app-db
property: connectionString
databases:
- name: django-app-db # A Render Postgres database named django-app-db running on a free instance
plan: free
```
A Blueprint acts as the single source of truth for configuring an interconnected set of services, databases, and [environment groups](configure-environment-variables#environment-groups). Whenever you update a Blueprint, Render automatically redeploys any affected services to apply the new configuration (you can [disable this](#disabling-automatic-sync)).
As your infrastructure grows over time, Blueprints become more and more helpful for managing changes and additions to it.
> **Do not manage a particular service, database, or environment group with more than one Blueprint.**
>
> If you do this, Render always attempts to apply the configuration from whichever Blueprint was synced most recently. If the Blueprints differ in their configuration, this can result in unpredictable behavior for your services.
>
> To avoid this scenario, make sure that each of your resources is managed by at most one Blueprint.
## Setup
1. From the root of a Git repo, create an empty file named `render.yaml`.
- Every Blueprint file uses the name `render.yaml` and resides at the root of a Git repo.
2. Populate `render.yaml` with the details of the resources you want to create and manage.
- If you're testing out Blueprints, try pasting the example Blueprint at the [top of this page](infrastructure-as-code).
- See also the complete [Blueprint specification reference](blueprint-spec).
3. Commit and push your changes to GitHub or GitLab.
4. Open the [Render Dashboard][dboard] and click **New > Blueprint**:
[img]
5. In the list that appears, click the **Connect** button for whichever repo contains your Blueprint.
- You'll first need to connect your [GitHub](github)/[GitLab](gitlab) account if you haven't yet.
6. In the form that appears, provide a name for your Blueprint and specify which branch of your repo to link.
- Each push to this branch that modifies `render.yaml` triggers a deploy of any added or modified resources.
7. Review the list of the changes that Render will apply based on the linked Blueprint:
[img]
If your Blueprint file contains errors, the page instead displays details about those errors.
8. If everything looks correct, click **Apply**.
You're all set! Render begins provisioning the resources defined in your Blueprint:
[img]
## Generating a Blueprint from existing services
You can generate a `render.yaml` file using any combination of your existing Render services. This is useful if you want to start managing those exact resources with a Blueprint, or if you want to [replicate those resources](#replicating-a-blueprint).
In the [Render Dashboard][dboard], select any number of your services, then click **Generate Blueprint** at the bottom of the page:
[img]
This opens a page where you can download or copy the generated `render.yaml` file. The page provides additional instructions for creating a Blueprint from that file.
> **Important:** For security, the generated `render.yaml` file includes the _names_ of all defined environment variables for the selected services, _but not their values_. Instead, the file sets `sync: false` for each environment variable.
>
> If you use your `render.yaml` file to create a Blueprint with _new_ services instead of your existing ones, you'll need to provide values for these environment variables. For details, see [Setting environment variables](blueprint-spec#setting-environment-variables).
## Replicating a Blueprint
You can create multiple Blueprints from a single `render.yaml` file. Each Blueprint creates and manages a completely independent set of resources.
The Blueprint creation flow displays a notice if your new Blueprint matches existing Render resources:
[img]
To replicate your Blueprint with a separate set of resources, click **Create New Resources**. Render appends a suffix to the name of each new resource to prevent collisions with your existing resources:
[img]
Click **Apply** to create the new resources as usual.
## Managing Blueprint resources
### Adding an existing resource
> **Do not add an existing resource to a Blueprint if it's already managed by _another_ Blueprint.**
>
> Doing so can lead to unpredictable behavior for your services.
You can add an existing Render resource to your Blueprint. To do so, add the resource's details to your `render.yaml` file as you would for a new resource. See all supported fields and values for each service type in the [Blueprint specification reference](blueprint-spec).
**Make sure to include all configuration options that are currently set for the resource in the Render Dashboard.** For most services, this includes the service's `name`, `type`, `plan` (instance type), `buildCommand`, `startCommand`, and so on. If you omit some of these options, your Blueprint will use a default value that almost definitely differs from your service's existing configuration.
When you next sync your Blueprint, Render applies the new configuration to the existing resource. The resource retains any existing environment variable values that aren't overwritten by the Blueprint.
### Modifying a resource outside of its Blueprint
You _can_ still make changes to a Blueprint-managed resource in the [Render Dashboard][dboard]. However, if any of those changes conflict with configuration defined in the Blueprint, they're overwritten the next time you sync your Blueprint.
Even if you _delete_ a Blueprint-managed resource in the Render Dashboard, Render recreates it the next time you sync your Blueprint! See [Deleting a resource](#deleting-a-resource).
### Deleting a resource
*Syncing a Blueprint never deletes an existing resource.* This is true even if you remove a resource definition from your Blueprint file, or if you disconnect your Blueprint from Render entirely. This is a safeguard against accidental deletions (for example, if you revert your Blueprint to a commit that predates the addition of a critical resource).
To delete a Blueprint-managed resource, _first_ remove it from your Blueprint, _then_ delete it in the [Render Dashboard][dboard] as usual.
> If you delete a resource in the Render Dashboard but _keep_ it in your Blueprint, Render _recreates_ that resource the next time you sync your Blueprint.
## Disabling automatic sync
By default, Render automatically updates affected resources every time you push Blueprint changes to your linked branch.
To instead control exactly when you sync a particular Blueprint, set *Auto Sync* to *No* on your Blueprint's Settings page:
[img]
You can then manually trigger a sync by clicking *Manual Sync* on your Blueprint's page.
## Supported fields and values
See the complete [Blueprint specification reference](blueprint-spec).
# Blueprint YAML Reference
Every [Render Blueprint](infrastructure-as-code) is backed by a YAML file that defines a set of interconnected services, databases, and environment groups.
A Blueprint file _must_ be named `render.yaml`, and it _must_ be located in the root directory of a Git repository.
This reference page provides an [example Blueprint file](#example-blueprint-file), along with documentation for supported fields.
## Example Blueprint file
The following `render.yaml` file demonstrates usage for _most_ supported fields. These fields are documented in further detail below.
*Show example Blueprint file*
```yaml:render.yaml
#################################################################
# Example render.yaml #
# Do not use this file directly! Consult it for reference only. #
#################################################################
previews:
generation: automatic # Enable preview environments
# List services *except* Render Postgres databases here
services:
# A web service on the Ruby native runtime
- type: web
runtime: ruby
name: sinatra-app
repo: https://github.com/render-examples/sinatra # Default: Repo containing render.yaml
numInstances: 3 # Manual scaling configuration. Default: 1 for new services
region: frankfurt # Default: oregon
plan: standard # Default: starter
branch: prod # Default: master
buildCommand: bundle install
preDeployCommand: bundle exec ruby migrate.rb
startCommand: bundle exec ruby main.rb
autoDeployTrigger: 'off' # Disable automatic deploys
maxShutdownDelaySeconds: 120 # Increase graceful shutdown period. Default: 30, Max: 300
domains: # Custom domains
- example.com
- www.example.org
envVars: # Environment variables
- key: API_BASE_URL
value: https://api.example.com # Hardcoded value
- key: APP_SECRET
generateValue: true # Generate a base64-encoded 256-bit value
- key: STRIPE_API_KEY
sync: false # Prompt for a value in the Render Dashboard
- key: DATABASE_URL
fromDatabase: # Reference a property of a database (see available properties below)
name: mydatabase
property: connectionString
- key: MINIO_PASSWORD
fromService: # Reference a value from another service
name: minio
type: pserv
envVarKey: MINIO_ROOT_PASSWORD
- fromGroup: my-env-group # Add all variables from an environment group
ipAllowList: # Optional (defaults to allow all); Enterprise workspaces only
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
# A web service that builds from a Dockerfile
- type: web
runtime: docker
name: webdis
repo: https://github.com/render-examples/webdis.git # Default: Repo containing render.yaml
rootDir: webdis # Default: Repo root
dockerCommand: ./webdis.sh # Default: Dockerfile CMD
scaling: # Autoscaling configuration
minInstances: 1
maxInstances: 3
targetMemoryPercent: 60 # Optional if targetCPUPercent is set
targetCPUPercent: 60 # Optional if targetMemory is set
healthCheckPath: /
registryCredential: # Default: No credential
fromRegistryCreds:
name: my-credentials
envVars:
- key: REDIS_HOST
fromService: # Reference a property from another service (see available properties below)
type: keyvalue
name: lightning
property: host
- key: REDIS_PORT
fromService:
type: keyvalue
name: lightning
property: port
- fromGroup: conc-settings
# A private service with an attached persistent disk
- type: pserv
runtime: docker
name: minio
repo: https://github.com/render-examples/minio.git # Default: Repo containing render.yaml
envVars:
- key: MINIO_ROOT_PASSWORD
generateValue: true # Generate a base64-encoded 256-bit value
- key: MINIO_ROOT_USER
sync: false # Prompt for a value in the Render Dashboard
- key: PORT
value: 10000
disk: # Persistent disk configuration
name: data
mountPath: /data
sizeGB: 10 # optional
# A Python cron job that runs every hour
- type: cron
name: date
runtime: python
schedule: '0 * * * *'
buildCommand: 'true' # ensure it's a string
startCommand: date
repo: https://github.com/render-examples/docker.git # optional
# A Dockerfile-based background worker
- type: worker
name: queue
runtime: docker
dockerfilePath: ./sub/Dockerfile # Optional
dockerContext: ./sub/src # Optional
branch: queue # Optional
# A static site
- type: web
name: my-blog
runtime: static
buildCommand: yarn build
staticPublishPath: ./build
previews:
generation: automatic # Enable service previews
buildFilter:
paths:
- src/**/*.js
ignoredPaths:
- src/**/*.test.js
headers:
- path: /*
name: X-Frame-Options
value: sameorigin
routes:
- type: redirect
source: /old
destination: /new
- type: rewrite
source: /a/*
destination: /a
ipAllowList: # Optional (defaults to allow all); Enterprise workspaces only
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
# A Key Value instance
- type: keyvalue
name: lightning
ipAllowList: # Required
- source: 0.0.0.0/0
description: everywhere
plan: free # Default: starter
maxmemoryPolicy: noeviction # Default: allkeys-lru
# List Render Postgres databases here
databases:
# A database with one read replica
- name: elephant
databaseName: mydb # Optional (Render may add a suffix)
user: adrian # Optional
ipAllowList: # Optional (defaults to allow all)
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
readReplicas:
- name: elephant-replica
# A database that allows only private network connections
- name: private database
databaseName: private
ipAllowList: [] # No entries in the IP allow list
# A database with specified disk size
- name: pachyderm
plan: basic-1gb
diskSizeGB: 35
# A database that enables high availability
- name: highly available database
plan: pro-8gb
highAvailability:
enabled: true
# Environment groups
envVarGroups:
- name: conc-settings
envVars:
- key: CONCURRENCY
value: 2
- key: SECRET
generateValue: true
- name: stripe
envVars:
- key: STRIPE_API_URL
value: https://api.stripe.com/v2
```
## IDE validation
The Render Blueprint specification is served from [SchemaStore.org](https://www.schemastore.org/json/), which many popular IDEs use to provide live validation and autocompletion for JSON and YAML files.
For VS Code, install the [YAML extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) to enable validation of `render.yaml` files:
[img]
If your IDE _doesn't_ integrate with SchemaStore.org, the Blueprint specification is also hosted at `https://render.com/schema/render.yaml.json` in JSON Schema format. Consult your IDE's documentation to learn how to use this schema for validation.
## Root-level fields
The following fields are valid at the root level of a `render.yaml` file:
| Field | Description |
|--------|--------|
| `services` | A list of _non-Postgres_ services to manage with the Blueprint. Each entry is an object that represents a single service. See all [service fields](#service-fields). Services in this top-level list keep their currently assigned environment (if any) after each sync. - To move a service into a specific environment, instead define it in the `services` list for that [environment](#environment-fields). - To remove a service from its current environment, instead define it under the [`ungrouped`](#ungrouped) field. **Do not define the same service in more than one location.** |
| `databases` | A list of Postgres databases to manage with the Blueprint. Each entry is an object that represents a single database. See all [database fields](#database-fields). Databases in this top-level list keep their currently assigned environment (if any) after each sync. - To move a database into a specific environment, instead define it in the `databases` list for that [environment](#environment-fields). - To remove a database from its current environment, instead define it under the [`ungrouped`](#ungrouped) field. **Do not define the same database in more than one location.** |
| `envVarGroups` | A list of [environment groups](configure-environment-variables#environment-groups) to manage with the Blueprint. Each entry is an object that represents a single environment group. See [supported fields](#environment-groups). Environment groups in this top-level list keep their currently assigned environment (if any) after each sync. - To move an environment group into a specific environment, instead define it in the `envVarGroups` list for that [environment](#environment-fields). - To remove an environment group from its current environment, instead define it under the [`ungrouped`](#ungrouped) field. **Do not define the same environment group in more than one location.** |
| `projects` | A list of [projects](projects) to manage with the Blueprint. A project defines one or more `environments`, each of which lists the services and environment groups that belong to it. For details, see [Projects and environments](#projects-and-environments). |
| `ungrouped` | An object for defining resources that should not belong to any [environment](#projects-and-environments). Can contain optional fields `services`, `databases`, and `envVarGroups`, each of which matches the format of its root-level counterpart. `ungrouped: services: - type: web name: my-service #...` Moving a resource definition into this object removes it from its current [environment](#projects-and-environments), guaranteeing that it is "ungrouped". In contrast, root-level definitions keep their currently assigned environment (if any). **Do not define the same resource in more than one location.** |
| `previews.generation` | The generation mode to use for [preview environments](preview-environments). `previews: generation: manual` Supported values include: - `off` - `manual` - `automatic` For details on each, see [Manual vs. automatic preview environments](preview-environments#manual-vs-automatic-preview-environments). If you omit this field, preview environments are disabled for any linked Blueprints. Setting the deprecated field `previewsEnabled: true` is equivalent to setting this field to `automatic`. This field does not affect configuration for individual [service previews](service-previews). |
| `previews.expireAfterDays` | The number of days to retain a [preview environment](preview-environments) that receives no updates. After this period, Render automatically deprovisions the preview environment to help reduce your compute costs. By default, preview environments are retained indefinitely until their associated pull request is closed. For details, see [Automatic expiration](preview-environments#automatic-expiration). |
## Service fields
Each entry in a Blueprint file's `services` list is an object that represents a single, _non-Postgres_ service. (You define Postgres databases in the [`databases` list](#database-fields).)
See below for supported fields.
### Essential fields
These fields pertain to a service's core configuration (name, runtime, region, and so on).
| Field | Description |
|--------|--------|
| `name` | **Required.** The service's name. Provide a unique name for each service in your Blueprint file. If you add the name of an _existing_ service to your Blueprint file, Render attempts to apply the Blueprint's configuration to that existing service. |
| `type` | **Required.** The type of service. One of the following: - `web` for a [web service](web-services) _or_ [static site](static-sites) - For a static site, you also set [`runtime: static`](#runtime). - `pserv` for a [private service](private-services) - `worker` for a [background worker](background-workers) - `cron` for a [cron job](cronjobs) - `keyvalue` for a [Render Key Value instance](key-value) - `redis` is a deprecated alias for `keyvalue`. You can't modify this value after creation. You define Render Postgres databases separately, in the [`databases`](#database-fields) list. |
| `runtime` | **Required** unless [`type`](#type) is `keyvalue` or `redis`. The service's runtime. Supported values include: **Native language runtimes** - `node` - `python` - `elixir` - `go` - `ruby` - `rust` **Special-case runtimes** - `docker` for services that [build an image](docker#building-from-a-dockerfile) from a Dockerfile. - `image` for services that [pull a prebuilt image](deploying-an-image) from a registry. - `static` for [static sites](static-sites) You can't modify this value after creation. This field replaces the `env` field (`env` is still supported but is discouraged). |
| `plan` | The service's instance type ([see pricing](pricing#services)). One of the following: - `free` (not available for private services, background workers, or cron jobs) - `starter` - `standard` - `pro` - `pro plus` The following additional instance types are available for [web services](web-services), [private services](private-services), and [background workers](background-workers): - `pro max` - `pro ultra` **If you omit this field:** - Render uses `starter` for a new service. - Render retains the current instance type for an existing service. |
| `previews.generation` | The preview generation mode to use for this service's [pull request previews](service-previews). Supported values include: - `manual` - `automatic` For details on each, see [Manual vs. automatic PR previews](service-previews#manual-vs-automatic-pr-previews). If you omit this field, pull request previews are disabled for the service. Setting the deprecated field `pullRequestPreviewsEnabled: true` is equivalent to setting this field to `automatic`. This field does not affect configuration for [preview environments](preview-environments). |
| `previews.numInstances` | The number of instances to use for this service in [preview environments](preview-environments). If you omit this field, preview instances use the same number of instances as the base service. If the base service uses autoscaling, preview instances use the minimum number of instances for the base service. |
| `previews.plan` | The instance type to use for this service in [preview environments](preview-environments). If you omit this field, preview instances use the same instance type as the base service. |
| `buildCommand` | **Required** for non-Docker-based services. The command that Render runs to [build your service](deploys#build-command). Basic examples include: - `npm install` (Node.js) - `pip install -r requirements.txt` (Python) |
| `startCommand` | **Required** for non-Docker-based services. The command that Render runs to [start your service](deploys#start-command). Basic examples include: - `npm start` (Node.js) - `gunicorn your_application.wsgi` (Python) Docker-based services set the optional [`dockerCommand`](#dockercommand) field instead of this field. |
| `schedule` | **Required** for [cron jobs](cronjobs), omit otherwise. The schedule for running the cron job, as a [cron expression](cronjobs#setup). |
| `preDeployCommand` | If specified, this command runs _after_ the service’s [`buildCommand`](#buildcommand) but _before_ its [`startCommand`](#startcommand). Recommended for running database migrations and other pre-deploy tasks. Learn more about the [pre-deploy command](deploys#pre-deploy-command). |
| `region` | The [region](regions) to deploy the service to. One of the following: - `oregon` (default) - `ohio` - `virginia` - `frankfurt` - `singapore` You can't modify this value after creation. This field does not apply to [static sites](static-sites). If omitted, the default value is `oregon`. |
| `repo` | For Git-based services, the URL of the GitHub/GitLab repo to use. Your Git provider account must have access to the repo. If omitted, Render uses the repo that contains the `render.yaml` file itself. For services that pull a prebuilt Docker image, set [`image`](#image) instead of this field. |
| `branch` | For Git-based services, the branch of the linked [`repo`](#repo) to use. If omitted, Render uses the repo's default branch. **If you're using [preview environments](preview-environments), you probably _don't_ want to set this field.** If you _do_ set it, Render uses the specified branch in all preview environments, _instead of_ your pull request's associated branch. This prevents you from testing code changes in the preview environment. |
| `autoDeployTrigger` | Sets the [automatic deploy](deploys#configuring-auto-deploys) behavior for a Git-based service. This field replaces the deprecated `autoDeploy` field. If you include both, this field takes precedence. One of the following: - `commit`: Trigger a deploy on each commit to the service's linked branch. - Equivalent to the deprecated setting `autoDeploy: true` - `checksPass`: Trigger a deploy only if the linked branch's CI checks pass. - `off`: Disable auto-deploys. - Equivalent to the deprecated setting `autoDeploy: false` This field has no effect for services that [deploy a prebuilt Docker image](deploying-an-image). **If you omit this field:** - Render uses `commit` for a new service. - Render retains the current value for an existing service. |
| `domains` | [Web services](web-services) and [static sites](static-sites) only. A list of [custom domains](custom-domains) for the service. Internet-accessible services are always reachable at their `.onrender.com` subdomain. For each root domain in the list, Render automatically adds a `www.` subdomain that redirects to the root domain. For each `www.` subdomain in the list, Render automatically adds the corresponding root domain and redirects it to the `www.` subdomain. |
| `healthCheckPath` | [Web services](web-services) only. The path of the service's [health check endpoint](health-checks) for zero-downtime deploys. |
| `maxShutdownDelaySeconds` | [Web services](web-services), [private services](private-services), and [background workers](background-workers) only. The maximum amount of time (in seconds) that Render waits for your application process to exit gracefully after sending it a `SIGTERM` signal. For details, see [Zero-downtime deploys](deploys#zero-downtime-deploys). After this delay, Render terminates the process with a `SIGKILL` signal if it's still running. Render most commonly shuts down instances as part of redeploying your service or scaling it down. Set this field to give instances more time to finish any existing work before termination. This value must be an integer between `1` and `300`, inclusive. If omitted, the default value is `30`. |
### Docker
The following fields are specific to [Docker-based services](docker). This includes both services that build an image with a `Dockerfile` ([`runtime: docker`](#runtime)) and services that pull a prebuilt image from a registry ([`runtime: image`](#runtime)).
#### Building from a `Dockerfile`
| Field | Description |
|--------|--------|
| `dockerCommand` | The command to run when starting the Docker-based service. If omitted, Render uses the `CMD` defined in the `Dockerfile`. |
| `dockerfilePath` | The path to the service's `Dockerfile`, relative to the repo root. Typically used for services in a [monorepo](monorepo-support). If omitted, Render uses `./Dockerfile`. |
| `dockerContext` | The path to the service's Docker build context, relative to the repo root. Typically used for services in a [monorepo](monorepo-support). If omitted, Render uses the repo root. |
| `registryCredential` | If your `Dockerfile` references any private images, you must specify a valid credential that can access those images. This field uses the following format: `registryCredential: fromRegistryCreds: name: my-credentials # The name of a credential you've added to your workspace` Add registry credentials in the [Render Dashboard][dboard] from your Workspace Settings page, or via the [Render API](https://api-docs.render.com/reference/create-registry-credential). |
#### Pulling a prebuilt image
| Field | Description |
|--------|--------|
| `image` | Details for the Docker image to pull from a registry. This field uses the following format: `image: url: docker.io/my-name/my-image:latest creds: # Only for private images fromRegistryCreds: name: my-credential-name # The name of a credential you've added to your workspace` Provide `creds` only if you're pulling a private image. Add registry credentials in the [Render Dashboard][dboard] from your Workspace Settings page, or via the [Render API](https://api-docs.render.com/reference/create-registry-credential). For more information, see [Deploy a Prebuilt Docker Image](deploying-an-image). |
### Scaling
> **Note the following about [**scaling**](scaling):**
>
> - You can't scale a service with an attached [persistent disk](disks).
> - Autoscaling requires a [**Professional** workspace](professional-features) or higher.
> - Manual scaling is available for all workspaces.
> - If you add an existing service to a Blueprint, that service retains any existing autoscaling settings unless you add the [`scaling`](#scaling) field in your Blueprint.
> - Autoscaling is disabled in [preview environments](preview-environments).
> - Instead, autoscaled services always run a number of instances equal to their [`minInstances`](#scaling-1).
| Field | Description |
|--------|--------|
| `numInstances` | For a [manually scaled](scaling#manual-scaling) service, the number of instances to scale the service to. **If you omit this field:** - Render uses `1` for a new service. - Render retains the current value for an existing service. **This value has no effect for services with autoscaling enabled.** Configure autoscaling behavior with the [`scaling`](#scaling-1) field. |
| `scaling` | For an [autoscaled](scaling#autoscaling) service, configuration details for the service's autoscaling behavior. Example: `scaling: minInstances: 1 # Required maxInstances: 3 # Required targetMemoryPercent: 60 # Optional if targetCPUPercent is set (valid: 1-90) targetCPUPercent: 60 # Optional if targetMemory is set (valid: 1-90)` |
### Build
| Field | Description |
|--------|--------|
| `buildFilter` | File paths in the service's repo to include or ignore when determining whether to trigger an automatic build. Especially useful for [monorepos](monorepo-support#setting-build-filters). Build filter paths use [glob syntax](monorepo-support#filter-syntax). They are always relative to the repo's root directory. When synced, this value _fully replaces_ an existing service's build filter settings. If you _omit_ this field for a service with existing build filter settings, Render _replaces_ those settings with empty lists. `buildFilter: paths: # Only trigger a build with changes to these files - src/**/*.js ignoredPaths: # Ignore these files, even if they match a path in 'paths' - src/**/*.test.js` |
| `rootDir` | The service's root directory within its repo. Changes to files _outside_ the root directory do not trigger a build for the service. Set this when working in a [monorepo](monorepo-support#setting-a-root-directory). If omitted, Render uses the repo's root directory. |
### Disks
Attach a [persistent disk](disks) to a compatible service with the `disk` field:
```yaml
disk:
name: app-data # Required field
mountPath: /opt/data # Required field
sizeGB: 5 # Default: 10
```
You can modify the `name` and `mountPath` of an existing disk. You can _increase_ the `sizeGB` of an existing disk, but you can't reduce it.
### Static sites
The following fields are specific to [static sites](static-sites):
| Field | Description |
|--------|--------|
| `staticPublishPath` | **Required.** The path to the directory that contains the static files to publish, relative to the repo root. Common examples include `./build` and `./dist`. |
| `headers` | Configuration details for a static site's [HTTP response headers](static-site-headers). Example: `headers: # Adds X-Frame-Options: sameorigin to all site paths - path: /* name: X-Frame-Options value: sameorigin # Adds Cache-Control: must-revalidate to /blog paths - path: /blog/* name: Cache-Control value: must-revalidate` You can modify existing header rules and add new ones. Render _preserves_ any existing header rules that are not included in the Blueprint file. |
| `routes` | Configuration details for a static site's [redirect and rewrite routes](redirects-rewrites). Example: `routes: # Redirect (HTTP status 301) from /a to /b - type: redirect source: /a destination: /b # Rewrite all /app/* requests to /app - type: rewrite source: /app/* destination: /app` You can modify existing routing rules and add new ones. Render _preserves_ any existing routing rules that are not included in the Blueprint file. |
### Render Key Value
You define Render Key Value instances in the `services` field of `render.yaml` alongside your other non-Postgres services. A Key Value instance has the [`type`](#type) `keyvalue` (or its deprecated alias `redis`).
#### Example definitions
**Show example Key Value definitions**
```yaml
services:
# A Key Value instance that defines all available fields
- type: keyvalue
name: thunder
ipAllowList: # Allow external connections from only these CIDR blocks
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
region: frankfurt # Default: oregon
plan: pro # Default: starter
previewPlan: starter # Default: use the value for 'plan'
maxmemoryPolicy: allkeys-lru # Default: allkeys-lru)
# A Key Value instance that allows all external connections
- type: keyvalue
name: lightning
ipAllowList: # Allow external connections from everywhere
- source: 0.0.0.0/0
description: everywhere
# A Key Value instance that allows only internal connections
- type: keyvalue
name: private cache
ipAllowList: [] # Only allow internal connections
```
#### Key-Value-specific fields
| Field | Description |
|--------|--------|
| `ipAllowList` | **Required.** See [Data access control](#data-access-control). |
| `maxmemoryPolicy` | The Key Value instance's eviction policy for when it reaches its maximum memory limit. One of the following: - `allkeys-lru` (default) - `volatile-lru` - `allkeys-random` - `volatile-random` - `volatile-ttl` - `noeviction` For details on these policies, see the [Render Key Value documentation](key-value#maxmemory-policy). |
### Environment variables
See [Setting environment variables](#setting-environment-variables).
## Database fields
Each entry in a Blueprint file's `databases` list is an object that represents a Render Postgres instance.
See below for supported fields.
### Example definitions
**Show example database definitions**
```yaml
databases:
# A basic-4gb database instance with one read replica
- name: prod # Required
postgresMajorVersion: '18' # Default: most recent supported version
region: frankfurt # Default: oregon
plan: basic-4gb # Default: basic-256mb
databaseName: prod_app # Default: generated value based on name
user: app_user # Default: generated value based on name
ipAllowList: # Default: allows all connections
- source: 203.0.113.4/30
description: office
- source: 198.51.100.1
description: home
readReplicas: # Default: does not add any read replicas
- name: prod-replica
# A database that allows only private network connections
- name: private database
databaseName: private
ipAllowList: [] # Only allow internal connections
# A database that enables high availability
- name: highly available database
plan: pro-16gb
highAvailability:
enabled: true
```
### Essential fields
| Field | Description |
|--------|--------|
| `name` | **Required.** The Postgres instance's name. Provide a unique name for each service in your Blueprint file. If you add the name of an _existing_ instance to your Blueprint file, Render attempts to apply the Blueprint's configuration to that existing instance. You can't modify this value after creation. |
| `plan` | The database's instance type ([see pricing](pricing#postgresql)). One of the following: **View values for plan** **Current instance types:** - `free` - `basic-256mb` - `basic-1gb` - `basic-4gb` - `pro-4gb` - `pro-8gb` - `pro-16gb` - `pro-32gb` - `pro-64gb` - `pro-128gb` - `pro-192gb` - `pro-256gb` - `pro-384gb` - `pro-512gb` - `accelerated-16gb` - `accelerated-32gb` - `accelerated-64gb` - `accelerated-128gb` - `accelerated-256gb` - `accelerated-384gb` - `accelerated-512gb` - `accelerated-768gb` - `accelerated-1024gb` **[**Legacy instance types**](postgresql-legacy-instance-types):** - `starter` - `standard` - `pro` - `pro plus` You cannot create new databases on a [legacy instance type](postgresql-legacy-instance-types). You can move a database from a legacy instance type to a current instance type, but you can't move it back. **If you omit this field:** - Render uses `basic-256mb` for a new database. - Render retains the current instance type for an existing database. |
| `previewPlan` | The instance type to use for this database in [preview environments](preview-environments). If you omit this field, preview instances use the same instance type as the primary database (specified by [`plan`](#plan-1)).
> If your primary database uses a new [flexible instance type](postgresql-refresh), you cannot specify a _non_-flexible instance type for `previewPlan` (or vice versa).
|
| `diskSizeGB` | The database's disk size, in GB. Not valid for [legacy instance types](postgresql-legacy-instance-types), which have a fixed disk size. This value must be either `1` or a multiple of `5`. You can increase disk size, but you can't _decrease_ it. **If you omit this field:** - For a new database, Render uses a default disk size based on the instance type's tier: - Free: 1 GB - Basic: 15 GB - Pro: 100 GB - Accelerated: 250 GB - For an existing database, Render retains the current disk size. |
| `previewDiskSizeGB` | The disk size to use for this database in [preview environments](preview-environments). If you omit this field, preview instances use the same disk size as the primary database (specified by [`diskSizeGB`](#disksizegb)). |
| `region` | The [region](regions) to deploy the instance to. One of the following: - `oregon` (default) - `ohio` - `virginia` - `frankfurt` - `singapore` You can't modify this value after creation. If omitted, the default value is `oregon`. |
| `ipAllowList` | See [Data access control](#data-access-control). |
### PostgreSQL settings
| Field | Description |
|--------|--------|
| `postgresMajorVersion` | The major version number of PostgreSQL to use, as a string (e.g., `"17"`). If omitted, Render uses the most recent version supported by the platform (currently ⬇️
[img] Similarly, you can view logs for the execution of a [one-off job](one-off-jobs) from the associated service's *Jobs* page. ## Log limits ### Retention period Render's log retention period depends on your workspace's plan (see the [pricing page](pricing)): | Workspace Plan | Retention Period | | ------------------------- | ---------------- | | Hobby | 7 days | | Professional | 14 days | | Organization / Enterprise | 30 days | Logs older than your current rentention period are no longer available, even if you upgrade your plan to extend the period. If you need to retain logs for a longer period, you can [stream your logs to a syslog-compatible provider](log-streams). ### Rate limit Render processes a maximum of 6,000 application-generated log lines per minute for each running instance of a service. If an instance generates logs in excess of this limit, Render drops the excess log lines. Dropped log lines don't appear in the log explorer or in [log streams](log-streams). # Streaming Render Service Logs You can stream the logs generated by your Render services to any logging provider with a TLS-enabled [syslog](https://en.wikipedia.org/wiki/Syslog) endpoint, such as Datadog or Sumo Logic. This includes [HTTP request logs](logging#http-request-logs) for *Professional* workspaces and higher. After you set a default stream destination for your workspace, all of your supported services start streaming their logs to that destination. You can [override this](#overriding-defaults) for individual services. > Render does not emit logs for [static sites](static-sites). ## Setup 1. From your workspace home in the [Render Dashboard][dboard], click *Integrations > Observability* in the left pane. 2. Scroll down to the *Log Streams* section: [img] 3. Under *Default destination*, click *+ Set default*. The following dialog appears: [img] 4. Provide your syslog endpoint URL in the *Log Endpoint* field. - Use the format `HOST:PORT` (for example, `logs.papertrailapp.com:34302`). - For help finding the endpoint URL with common providers, [see below](#finding-your-syslog-endpoint). 5. If Render needs to include an authentication token with all reported logs, provide it in the *Token* field. - This is required for logging providers that use a single syslog endpoint for multiple users, such as Datadog. 6. Click *Save Changes*. 7. Toggle *Include logs from preview instances* to configure whether your log stream includes logs from your [service previews](service-previews) and [preview environments](preview-environments). You're all set! Logs from Render will start to appear in your provider's feed shortly. ## Overriding defaults [*Professional* workspaces](professional-features) and higher can override log stream settings for individual services: | Custom Setting | Hobby | Professional | Organization / Enterprise | |--------|--------|--------|--------| | Omit individual services from log stream | ❌ | 🟢 | 🟢 | | Set a custom destination for individual services | ❌ | ❌ | 🟢 | 1. In the [Render Dashboard][dboard], open the Settings page for the service you want to override and scroll down to the *Log Stream* section: [img] 2. Open the *•••* menu and click *Override*. The following dialog appears: [img] 3. Select *Forward to a different destination* or *Don't forward this service's logs*. - Forwarding to a different destination requires an Organization workspace or higher. 4. Provide any necessary details for the selected option and click *Save override*. You're all set! Your service now uses its own custom log stream settings: [img] You can revert this custom configuration by clicking *Reset to default*. ## Reporting format Render streams logs to your provider's syslog endpoint over TCP. Log lines are formatted according to [RFC5424](https://tools.ietf.org/html/rfc5424), which is supported by most popular providers. Log streams do _not_ support: - Insecure (non-TLS-enabled) endpoints - Providers that require a custom log format > If you encounter issues integrating with a syslog-compatible provider, please let us know at *support@render.com*. A formatted log line looks like this: ``` <0>1 2021-03-31T16:00:00-08:00 test-service cron-12345 74440 cron-12345 - hello this is a test ``` Render annotates each log line with: - The corresponding service's slug - The type of service (`web`, `cron`, etc.) - A unique identifier for the instance - Use this value to track your service between deploys, or to distinguish between multiple instances if you're running more than one. If you're using a standard format like `logfmt` or `json`, Render maps the `level` field to an appropriate syslog priority. Otherwise, Render makes a best effort to parse log levels, defaulting to `INFO`. ## Finding your syslog endpoint Consult your logging provider's documentation to obtain your syslog endpoint and any necessary token. Instructions for certain providers are also available below. > If there’s a logging provider you’d us to add to this list, please submit a [feature request](https://feedback.render.com). ### Better Stack (previously Logtail) Create a new source in [Better Stack Logs](https://logs.betterstack.com/) with the platform `Render`: [img] Then, when adding your log stream in Render: - Provide `in.logs.betterstack.com:6514` as the **Log Endpoint**. - Provide the **source token** from Better Stack as the **Token**. For more information, see the [Better Stack documentation](https://betterstack.com/docs/logs/render). ### Datadog See [this section](datadog#streaming-service-logs-and-metrics). ### highlight.io To stream logs to your existing highlight.io project: - Provide `syslog.highlight.io:34302` as the **Log Endpoint**. - Provide your highlight project ID as the **Token**. - Your highlight project ID is shown in the top left of your project page. For more information, see the [highlight.io documentation](https://www.highlight.io/docs/getting-started/backend-logging/hosting/render). ### Mezmo (previously LogDNA) > We've observed high rates of connection failures with Mezmo's syslog endpoint and do not recommend using them with Render at this time. Log in to your Mezmo account and navigate to the [sources page](https://app.logdna.com/pages/add-source). Select **syslog** on the left sidebar to see your syslog endpoint. [img] ### Papertrail Log in to your account and navigate to the [setup page](https://papertrailapp.com/systems/setup?type=system&platform=unix#unix-manual) to find your Syslog endpoint: [img] If you use the same Papertrail account to collect logs from multiple providers, you can optionally [generate a unique endpoint for your Render services](https://papertrailapp.com/destinations/new). ### SolarWinds Follow the instructions for [sending logs using syslog](https://documentation.solarwinds.com/en/success_center/observability/content/configure/configure-logs-syslog.htm). - Set the **Log Endpoint** to your organization's syslog collector endpoint. This endpoint has the format `syslog.collector.xx-yy.cloud.solarwinds.com:6514`, where `xx-yy` represents the data center your organization uses. See [Data centers and endpoint URIs](https://documentation.solarwinds.com/en/success_center/observability/content/system_requirements/endpoints.htm) to find the exact URL. - Provide your API ingestion token as the *Token*. - Your API ingestion token is found in the Token field. ### Sumo Logic Follow the instructions for [configuring a cloud syslog source](https://help.sumologic.com/docs/send-data/hosted-collectors/cloud-syslog-source/#configure-a-cloudsyslogsource). After you configure your source, Sumo Logic displays a modal with a *Token* and *Host*. Use these for your log stream's *Token* and *Log Endpoint*, respectively. # The Render CLI Use the Render CLI to manage your Render services and datastores directly from your terminal: [video] Among many other capabilities, the CLI supports: - Triggering service deploys, restarts, and one-off jobs - Opening a psql session to your database - Viewing and filtering live service logs The CLI also supports [non-interactive use](#non-interactive-mode) in scripts and CI/CD. > Please submit bugs and feature requests on the CLI's [public GitHub repository](https://github.com/render-oss/cli). ## Setup ### 1. Install **Homebrew** Run the following commands: ```shell brew update brew install render ``` **Linux/MacOS** Run the following command: ```shell curl -fsSL https://raw.githubusercontent.com/render-oss/cli/refs/heads/main/bin/install.sh | sh ``` **Direct download** 1. Open the CLI's [GitHub releases page](https://github.com/render-oss/cli/releases/). 2. Download the executable that corresponds to your system's architecture. If you use an architecture besides those provided, you can build from source instead. **Build from source** > We recommend building from source only if no other installation method works for your system. 1. [Install the Go programming language](https://golang.org/doc/install) if you haven't already. 2. Clone and build the CLI project with the following commands: ```shell git clone git@github.com:render-oss/cli.git cd cli go build -o render ``` After installation completes, open a new terminal tab and run `render` with no arguments to confirm. ### 2. Log in The Render CLI uses a **CLI token** to authenticate with the Render platform. Generate a token with the following steps: 1. Run the following command: ```shell render login ``` Your browser opens a confirmation page in the Render Dashboard. 2. Click **Generate token**. The CLI saves the generated token to its [local configuration file](#local-config). 3. When you see the success message in your browser, close the tab and return to your terminal. 4. The CLI prompts you to set your active workspace. You can switch workspaces at any time with `render workspace set`. You're ready to go! ## Common commands > **This is not an exhaustive list of commands.** > > - Run `render` with no arguments for a list of all available commands. > - Run `render help`[SERVICE_ID]` | Lists deploys for the specified service. Select a deploy to view its logs or open its details in the Render Dashboard. If you don't provide a service ID in interactive mode, the CLI prompts you to select a service. | | `deploys create`
`[SERVICE_ID]` | Triggers a deploy for the specified service. If you don't provide a service ID in interactive mode, the CLI prompts you to select a service. In [non-interactive mode](#non-interactive-mode), helpful options include: - `--wait` to block until the deploy completes (a failed deploy exits with a non-zero status) - `--commit [SHA]` to deploy a specific commit (Git-backed services only) - `--image [URL]` to deploy a specific Docker image tag or digest (image-backed services only) | | `psql`
`[DATABASE_ID]` | Opens a psql session to the specified PostgreSQL database. If you don't provide a database ID in interactive mode, the CLI prompts you to select a database. | | `ssh`
`[SERVICE_ID]` | Opens an SSH session to a running instance of the specified service. If you don't provide a service ID in interactive mode, the CLI prompts you to select a service. | ## Non-interactive mode By default, the Render CLI uses interactive, menu-based navigation. This default is great for manual use, but not for scripting or automation. Configure the CLI for non-interactive use in CI/CD and other automated environments with the following steps: ### 1. Authenticate via API key The Render CLI can authenticate using an API key instead of [`render login`](#2-log-in). Unlike CLI tokens, API keys do not periodically expire. For security, use this authentication method only for automated environments. 1. Generate an API key with [these steps](api#1-create-an-api-key). 2. In your automation's environment, set the `RENDER_API_KEY` environment variable to your API key: ```bash export RENDER_API_KEY=rnd_RUExip… ``` > If you provide an API key this way, it always takes precedence over CLI tokens you generate with `render login`. ### 2. Set non-interactive command options Set the following options for _all_ commands you run in non-interactive mode: | Flag | Description | |--------|--------| | `-o` / `--output` | Sets the output format. For automated environments, specify `json` or `yaml`. Also supports `text` for unstructured text output, along with the default value `interactive`. | | `--confirm` | Skips any confirmation prompts that the command would otherwise display. | For example, to list the active workspace's services in JSON format: ```shell render services --output json --confirm ``` ### Example: GitHub Actions This example action provides similar functionality to Render's [automatic Git deploys](deploys#automatic-git-deploys). You could disable auto-deploys and customize this action to trigger deploys with different conditions. To use this action, first set the following secrets in your repository: | Secret | Description | | ------------------- | -------------------------------------------------- | | `RENDER_API_KEY` | A valid Render [API key](api#1-create-an-api-key) | | `RENDER_SERVICE_ID` | The ID of the service you want to deploy | ```yaml name: Render CLI Deploy run-name: Deploying via Render CLI # Run this workflow when code is pushed to the main branch. on: push: branches: - main jobs: Deploy-Render: runs-on: ubuntu-latest steps: # Downloads the Render CLI binary and adds it to the PATH. # To prevent breaking changes in CI/CD, we pin to a # specific CLI version (in this case 1.1.0). - name: Install Render CLI run: | curl -L https://github.com/render-oss/cli/releases/download/v1.1.0/cli_1.1.0_linux_amd64.zip -o render.zip unzip render.zip sudo mv cli_v1.1.0 /usr/local/bin/render - name: Trigger deploy with Render CLI env: # The CLI can authenticate via a Render API key without logging in. RENDER_API_KEY: ${{ secrets.RENDER_API_KEY }} CI: true run: | render deploys create ${{ secrets.RENDER_SERVICE_ID }} --output json --confirm ``` ## Local config By default, the Render CLI stores its local configuration at the following path: ``` $HOME/.render/cli.yaml ``` You can change this file path by setting the `RENDER_CLI_CONFIG_PATH` environment variable. ## Managing CLI tokens For security, CLI tokens periodically expire. If you don't use the Render CLI for a while, you might need to re-authenticate with `render login`. View a list of your active CLI tokens from your [Account Settings page](https://dashboard.render.com/u/settings#render-cli-tokens) in the Render Dashboard. You can manually revoke a CLI token that you no longer need or that might be compromised. Expired and revoked tokens tokens do not appear in the list. # Render MCP Server Render's *Model Context Protocol* (*MCP*) server enables you to manage your Render infrastructure directly from compatible AI apps, such as Cursor and Claude Code: [video] Using natural language prompts, you can: - Spin up new services - Query your databases - Analyze metrics and logs ...and more! For inspiration, see some [example prompts.](#example-prompts) *What is MCP?* [*Model Context Protocol*](https://modelcontextprotocol.io/introduction) (*MCP*) is an open standard for connecting AI applications to external tools and data. An *MCP server* exposes a set of actions that AI apps can invoke to help fulfill relevant user prompts (e.g., "Find all the documents I edited yesterday"). To perform an action, an MCP server often calls an external API, then packages the result into a standardized format for the calling application. ## How it works The Render MCP server is hosted at the following URL: ``` https://mcp.render.com/mcp ``` You can configure compatible AI apps (such as [Cursor](https://docs.cursor.com/context/mcp) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)) to communicate with this server. When you provide a relevant prompt, your tool intelligently calls the MCP server to execute supported platform actions: [img] **In the example diagram above:** 1. A user prompts Cursor to "List my Render services". 2. Cursor intelligently detects that the Render MCP server supports actions relevant to the prompt. 3. Cursor directs the MCP server to execute the `list_services` "[tool](https://modelcontextprotocol.io/docs/concepts/tools)", which calls the Render API to fetch the corresponding data. > To explore the implementation of the MCP server itself, see the open-source project: ## Setup ### 1. Create an API key The MCP server uses an [API key](api#1-create-an-api-key) to authenticate with the Render platform. Create an API key from your [Account Settings page](https://dashboard.render.com/settings#api-keys): [img] > **Render API keys are broadly scoped.** They grant access to all workspaces and services your account can access. > > Before proceeding, make sure you're comfortable granting these permissions to your AI app. The Render MCP server currently supports only one potentially destructive operation: modifying an existing service's environment variables. ### 2. Configure your tool Next, we'll configure your AI app to use Render's hosted MCP server. Most compatible apps define their MCP configuration in a JSON file (such as `~/.cursor/mcp.json` for Cursor). Select the tab for your app: **Cursor** #### Cursor setup Add the following configuration to `~/.cursor/mcp.json`: ```json{3-8} { "mcpServers": { "render": { "url": "https://mcp.render.com/mcp", "headers": { "Authorization": "Bearer
Create a new database named user-db with 5 GB storage
Deploy an example Flask web service on Render using https://github.com/render-examples/flask-hello-world#### Data analysis
Using my Render database, tell me which items were the most frequently bought together
Query my read replica for daily signup counts for the last 30 days#### Service metrics
What was the busiest traffic day for my service this month?
What did my service's autoscaling behavior look like yesterday?#### Troubleshooting
Pull the most recent error-level logs for my API service
Why isn't my site at example.onrender.com working?## Supported actions The Render MCP server provides a "[tool](https://modelcontextprotocol.io/docs/concepts/tools)" for each platform action listed below (organized by resource type). Your AI app (the "MCP host") can combine these tools however it needs to perform the tasks you describe. > For more details on all available tools, see the [project README](https://github.com/render-oss/render-mcp-server). | Resource Type | Supported Actions | |--------|--------| | **Workspaces** | - List all workspaces you have access to - Set the current workspace - Fetch details of the currently selected workspace | | **Services** | - Create a new web service or static site - Other service types are not yet supported. - List all services in the current workspace - Retrieve details about a specific service - Update all environment variables for a service | | **Deploys** | - List the deploy history for a service - Get details about a specific deploy | | **Logs** | - List logs matching provided filters - List all values for a given log label | | **Metrics** | - Fetch performance metrics for services and datastores, including: - CPU / memory usage - Instance count - Datastore connection counts - Web service response counts, segmentable by status code - Web service response times (requires a **Professional** workspace or higher) - Outbound bandwidth usage | | **Render Postgres** | - Create a new database - List all databases in the current workspace - Get details about a specific database - Run a read-only SQL query against a specific database | | **Render Key Value** | - List all Key Value instances in your Render account - Get details about a specific Key Value instance - Create a new Key Value instance | ## Running locally > **We strongly recommend using Render's [hosted MCP server](#2-configure-your-tool) instead of running it locally.** > > The hosted MCP server automatically updates with new capabilities as they're added. Run locally only if required for your use case. You can install and run the Render MCP server on your local machine as a Docker container, or by running the executable directly: **Docker image** #### Docker setup > **This method requires `docker`.** With this configuration, your AI app pulls and runs the Render MCP server as a Docker container. Add JSON with the format below to your tool's MCP configuration (substitute `
[img]
Please see our [announcement blog post](blog/free-ddos-protection) to learn more about DDoS attacks and why we built this feature.
## Limitations
If you use wildcard custom subdomains and your own Cloudflare account, please see our [Custom Domains documentation](configure-cloudflare-dns#adding-a-wildcard-custom-domain-without-the-base-domain) for a specific configuration that may cause traffic to be incorrectly routed. If you have any questions, you can get in touch with us at support@render.com.
# Render Platform Maintenance
Render routinely performs infrastructure maintenance to improve platform performance, reliability, and security.
In _most_ cases, maintenance is completely transparent, with no interruption to your services.
## Service-affecting maintenance
> Maintenance _never_ changes a service's configuration details or instance type.
Certain types of maintenance (such as OS upgrades) do require brief downtime, specifically for services that provide persistent storage:
- [Render Postgres databases](postgresql)
- [Render Key Value instances](key-value)
- Services with an attached [persistent disk](disks)
To ensure the integrity of your data, Render spins down these service instances completely before spinning up their replacements. This process usually takes a few minutes. For Render Postgres databases with [high availability](postgresql-high-availability), this is reduced to less than one minute.
*What about other services?*
Services without attached storage ("stateless" services) remain available during maintenance windows, because they support [zero-downtime deploys](deploys#zero-downtime-deploys). Render can spin up new instances for these services before deprovisioning the old ones, ensuring there's always a routing destination for incoming traffic:
[diagram]
*For services that perform long-running tasks* (such as [background workers](background-workers)), make sure these services define logic to handle a graceful shutdown in the event of receiving a `SIGTERM` signal. Render sends this signal when spinning down an instance as part of maintenance (and as part of any zero-downtime deploy).
### Resolving maintenance deploy failures
> *For assistance resolving a maintenance deploy failure:*
>
> - See [Troubleshooting Your Deploy](troubleshooting-deploys) for common issues and solutions.
> - [Reach out to our support team](https://dashboard.render.com/?contact-support) in the Render Dashboard.
As part of service-affecting maintenance, Render deploys your services to new instances before spinning down the old ones. In certain cases, this deploy might fail. This most commonly occurs if your service's most recent deploys were failing _before_ maintenance began, indicating an issue with your service's current build and deploy configuration.
In the event of a deploy failure, Render keeps your old instance running (until a specified deadline) and continues routing traffic to it:
[diagram]
Render immediately notifies you by email if a maintenance deploy fails. This email includes a deadline for resolving the issue, after which Render will bring down the old instance. *If you do not resolve the issue before the deadline, your service will be taken offline.*
### Rescheduling maintenance
> *[*Free services*](free) do not support rescheduling maintenance.*
>
> Render might perform maintenance on a free service at any time, without advance notice.
If any of your paid services will experience downtime as part of a maintenance window, Render always provides advance notice via email _and_ in the [Render Dashboard][dboard]. Service-affecting maintenance windows usually occur no more than once every three months.
Whenever possible, Render provides the ability to reschedule a paid service's maintenance window to a more convenient time (usually within a few days of the original scheduled date). You can reschedule in the [Render Dashboard][dboard] or via the [Render API](https://api-docs.render.com/reference/update-maintenance).
### Triggering maintenance
Both the Render Dashboard and [API](https://api-docs.render.com/reference/trigger-maintenance) support _immediately_ triggering a service's scheduled maintenance.
The following actions _also_ trigger maintenance immediately, because they already involve replacing a service's current instance with a new one:
- Redeploying a service
- Restarting a Render Postgres database
- Suspending and resuming a Render Postgres database
- Changing the instance type for any service, Render Postgres database, or Render Key Value instance
# Render Platform Compliance and Certifications
The Render platform is fully compliant with the following security frameworks:
| Regulation / Framework | Description |
|--------|--------|
| *SOC 2 Type 2* | Validates an organization's security controls and their operational effectiveness via annual third-party audit. |
| *ISO 27001* | Defines a global standard of requirements for information security management systems (ISMS). |
In addition, Render supports [*HIPAA-enabled workspaces*](hipaa-compliance) for organizations that process and store US health data.
Render also maintains its own security policy and complies with the General Data Protection Regulation (GDPR).
## View compliance documentation
> *Some documents require an Organization or Enterprise workspace.* [See details.](#provided-documents)
Certificates, attestations, and other security policy documents are available from the [Document Center](https://dashboard.render.com/documents) in the Render Dashboard:
[img]
Open the Document Center by visiting [dashboard.render.com/documents](https://dashboard.render.com/documents) or by clicking *Compliance and documents* in the top-right corner of the dashboard:
[img]
### Provided documents
*All workspaces* can access the following documents:
- SOC 3 report
- GDPR DPA
*Organization and Enterprise workspaces* can access the following documents, which also require signing a non-disclosure agreement (NDA):
- SOC 2 Type 2 report
- ISO 27001 certificate
- Render security policy
# HIPAA on Render
> *HIPAA-enabled workspaces require an Organization or Enterprise plan.*
*HIPAA* is a United States federal law that sets standards for protecting individuals' healthcare data. It defines administrative, physical, and technical safeguards for organizations that process or store protected health information (PHI).
Render provides *HIPAA-enabled workspaces* for organizations subject to HIPAA requirements. These workspaces run services and datastores on access-restricted hosts, helping to secure any PHI processed or stored by your applications. Access to these hosts by Render staff is subject to strict controls.
## Setup
> *Before proceeding, review all [important considerations](#important-considerations) below.*
The following steps must be completed by a workspace admin:
1. In the [Render Dashboard][dboard], open your *Workspace Settings* page and scroll down to the *Compliance* section:
[img]
2. Click *Get Started*. This opens a confirmation flow to receive Render's Business Associate Agreement (BAA).
3. Review all enablement steps, best practices, and workspace details outlined in the confirmation flow.
4. After you complete the confirmation flow, Render emails you a link to sign the BAA.
5. After you sign the BAA, return to the *Compliance* section of your workspace settings. After about a minute, your HIPAA Compliance status updates to *Pending*:
[img]
6. When you're ready, click *Enable HIPAA* to initiate the enablement process.
- Before proceeding, review all details in the confirmation dialog that appears.
- If you don't initiate the enablement process manually, Render initiates it automatically 72 hours after you sign the BAA.
As part of enablement, Render redeploys all of your workspace's existing services and datastores to access-restricted hosts. Your services might become unavailable for a few minutes.
Render emails you when the enablement process begins, then a second time after it completes.
7. After the process completes, your HIPAA Compliance status updates to *Enabled*:
[img]
Your workspace is now ready to host HIPAA-compliant applications.
## Important considerations
*Before upgrading to a HIPAA-enabled workspace, note all of the following:*
- Upgrading to a HIPAA-enabled workspace is an irreversible action.
- An additional 20% fee applies to all usage (compute, storage, etc.) in a HIPAA-enabled workspace. The minimum monthly fee is $250.
- HIPAA-enabled workspaces cannot deploy or run [free instances](free).
- This is because free instances run on hosts that do not support restricted access for HIPAA compliance.
- If your workspace has existing free instances, Render migrates them to the smallest paid instance type as part of the upgrade process.
- Render also _suspends_ free web services migrated this way (Postgres and Key Value instances are not suspended). These services are not billed while suspended. You can resume them any time after upgrading.
- For [*Enterprise* plans](enterprise-orgs), Render upgrades _one_ of your workspaces to a HIPAA-enabled workspace.
- You specify which workspace to upgrade in your BAA.
- Your other workspaces are _not_ HIPAA-enabled. All HIPAA-compliant workflows must run in the HIPAA-enabled workspace.
- Even in a HIPAA-enabled workspace, you _must not_ include PHI in certain resources.
- For details, see [Where can I process and store PHI?](#where-can-i-process-and-store-phi)
- *A HIPAA-enabled workspace does not automatically make your applications HIPAA-compliant.*
- You are responsible for adhering to HIPAA regulations for all applications in your workspace.
- For more information, see Render's [shared responsibility model](shared-responsibility-model).
## Where can I process and store PHI?
> *Never process or store PHI on Render outside of a HIPAA-enabled workspace.*
Not all resources in a HIPAA-enabled workspace support HIPAA-compliant processing and storing of PHI. See the following table for details:
***Live services***
| Resource | PHI OK? | Details |
|--------|--------|--------|
| [Web services](web-services) | 🟢 | |
| [Static sites](static-sites) | ❌ | Static sites consist of static assets hosted at a publicly accessible URL. Those assets _must not_ include any PHI. |
| [Private services](private-services) | 🟢 | |
| [Background workers](background-workers) | 🟢 | |
| [Cron jobs](cronjobs) | 🟢 | |
| Service-generated [logs](logging) | ❌ | Never include PHI in any message logged by any Render service, whether at build time or runtime. |
| [Service previews](service-previews) and [preview environments](preview-environments) | 🟢 | Preview instances run on access-restricted hosts, just like their production counterparts. |
***Datastores***
| [Persistent disks](disks) | 🟢 | All disks and their daily snapshots are encrypted at rest. |
| [Render Postgres](postgresql) databases | 🟢 | Your primary databases, [read replicas](postgresql-read-replicas), and [high availability](postgresql-high-availability) standby databases all support HIPAA-compliant workflows. |
| [Render Key Value](key-value) instances | 🟢 | |
***Builds***
| Build artifacts | ❌ | This is the bundle generated by your service's [build command.](deploys#build-command) It includes application code, dependencies, static assets, and any other files needed to run your service. These generated files must not include PHI. |
| Infrastructure-as-code config | ❌ | This includes `render.yaml` files for [Blueprints](infrastructure-as-code), along with [Terraform](terraform-provider) configuration files. |
| Resource names | ❌ | Do not include PHI in the name you assign to _any_ resource, including: - Service names - Environment variable names - Secret file filenames - Table or column names in your database |
# Shared Responsibility Model
Render's security controls are predicated on the assumption that customers maintain robust internal controls. The effective use of the Render system relies heavily on customers actively managing their assigned security responsibilities. This includes safeguarding user data, controlling access, and upholding security protocols.
This document delineates Render's specific responsibilities alongside the customer's obligations and identifies areas of shared responsibility. It aims to guide customers in establishing comprehensive security practices.
Note that the procedures and controls listed here serve as foundational guidance. They are not exhaustive. Customers are encouraged to implement additional controls that align with their specific security needs and compliance requirements.
## Customer responsibilities
*Customer is responsible for:*
- Protecting all secrets within their organization
- Managing and reviewing user access to the Render system
- Implementing and enforcing data policies regarding the types of data entered into the Render system, ensuring data is transmitted securely and encrypted as necessary
- Keeping informed about communications from Render that affect system security, user obligations, or service availability
- Establishing and maintaining security controls for system-generated outputs and reports
- Compliance with relevant legal and regulatory requirements
- Security of application-level configurations
- Regular security assessments of their applications
- Endpoint protection of workstations used to access the Render system
- Developing and maintaining their own business continuity and disaster recovery plans
- Deleting their data from the Render system upon termination of services
## Render responsibilities
*Render is responsible for:*
- Making sure all underlying operating systems are patched and up to date
- All internal networking between services and databases
- Securing the infrastructure that hosts all hardware, software, networking, and facilities
- Managing the underlying servers, networks, and storage
- Ensuring that the runtime environments for supported programming languages and frameworks are secure and up to date
- Transparency about their operational status and any security breaches
- Securing the platform, which includes middleware and other integrated services that it provides
- Providing detailed documentation and guidelines on the security features of their platform.
## Shared responsibilities
*Customer and Render share responsibility for:*
- Monitoring and responding to incidents, depending on the nature of the incident and where it occurs in the stack
- Security training
- Data privacy management—both parties should cooperate to ensure that data privacy is maintained according to best practices and compliance requirements.
- Conducting regular reviews of their security practices
# Render Penetration Testing Policy
Render customers are welcome to carry out security assessments or penetration tests of their own Render-hosted services without prior approval from Render. This helps customers identify and remediate vulnerabilities in their application environments.
## Prohibited testing
Direct testing of Render's core infrastructure, APIs, or other services not provisioned for the individual customer's use is strictly forbidden without explicit consent from Render.
Testing of another Render user's infrastructure is not permitted without explicit consent.
Engaging in any form of Denial of Service (DoS) testing against Render infrastructure including customer environments is expressly prohibited. Render provides free [DDoS protection](ddos-protection) to all hosted services, and violating this policy by attempting DoS attacks jeopardizes the security and availability of services across our platform.
## Communicating with Render
If you discover a security issue within the Render product, please submit a report to our [Vulnerability Disclosure Program](https://hackerone.com/bde6ea21-8984-4f4c-89ca-55cc309228d2/embedded_submissions/new) immediately.
If Render detects abusive activities related to your security testing, we will reach out to you to stop your activities.
# Back Up Render Postgres to Amazon S3
In this guide we'll show you how to back up your Render Postgres instance to Amazon S3.
Render continually backs up all paid Render Postgres instances to provide [point-in-time recovery](postgresql-backups). For additional control, you can create a [cron job](cronjobs) that periodically backs up your data to Amazon S3.
You will need a [Render Postgres database](postgresql) and an [Amazon Web Services](https://aws.amazon.com/) (AWS) account for this guide.
By following this guide, you'll be able to:
1. [Create AWS credentials](#create-aws-credentials) that will enable working with Amazon S3.
2. [Configure and create a backup Cron Job](#configure-and-create-the-backup-cron-job) for your database.
3. [Validate that the backup is working.](#validate-the-cron-job)
## Create AWS Credentials
We will create credentials with AWS IAM to enable working with Amazon S3.
1. Open the AWS console and navigate to the IAM service. Open the Users view and select the `Add Users` button.
[img]
2. Enter a descriptive username, such as `Shared tier: `N. Virginia (us-east-1)` | | `Virginia, USA` | `Virginia (us-east-1)` | | `Frankfurt, Germany` | `Frankfurt (eu-central-1)` | | `Singapore` | `Singapore (ap-southeast-1)` | 3. Choose an authentication method. This guide assumes you are using a username and password for authentication. You could also use a [Certificate](https://www.mongodb.com/docs/manual/core/security-x.509/). 4. Create a user profile for the new database and make a note of your database username and password. You will create environment variables for these values in your Render service connecting to Atlas. 5. Update cluster connections under "Network Access". Add your Render service's [outbound IP addresses](outbound-ip-addresses). [img] 6. Under "Connection Method", select "Connect your Application". Pick the Mongo driver and version used in your Render service to create a [connection string URI](https://www.mongodb.com/docs/manual/reference/connection-string/). ## Connect to your application on Render 1. Return to the Render Dashboard and create [environment variables](configure-environment-variables) for `username` and `password` in your Render service using the database username and password your created above. - There are some characters that require special treatment. See the [MongoDB documentation on connection string formats](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-standard-connection-string-format) 2. Add connection details to your code by following the steps for your app's language or framework. That's it! Your Render service should now be able to connect to your MongoDB Atlas instance. ## Further reading MongoDB supports a variety of [drivers](https://www.mongodb.com/docs/drivers/). This guide highlights some of the most useful resources for Python and Node applications. ### [Python](https://www.mongodb.com/docs/drivers/python/) The method for adding a database connection to your Python application code depends on whether your application is synchronous or asynchronous. Use [Pymongo](https://www.mongodb.com/docs/drivers/pymongo/) in your application to connect to MongoDB (for synchronous applications) - [Tutorial for completing common database operations with Pymongo](https://pymongo.readthedocs.io/en/stable/tutorial.html) Use [Motor](https://www.mongodb.com/docs/drivers/motor/) in your Python app to connect to MongoDB Atlas (for asynchronous applications using either Tornado or asyncio. - [Tutorial for completing common database operations using Motor with Tornado](https://motor.readthedocs.io/en/stable/tutorial-tornado.html) - [Tutorial for completing common database operations using Motor with asyncio](https://motor.readthedocs.io/en/stable/tutorial-asyncio.html) ### [Node](https://www.mongodb.com/docs/drivers/node/current/quick-start/) - [Guide to CRUD operations for Interacting with the Database in Node Applications](https://www.mongodb.com/docs/drivers/node/current/fundamentals/crud/#std-label-node-crud-landing) # Connect to Render Key Value with ioredis This guide walks through connecting to a [Render Key Value](key-value) instance with [ioredis](https://github.com/luin/ioredis), the popular Node.js Redis client. > We recommend using the latest version of ioredis. This guide assumes a minimum version of `5.0.0`. ## Key Value setup 1. Create a Render Key Value instance with [these steps](key-value#create-your-key-value-instance). 2. Obtain your instance's internal URL from its *Connect* menu in the [Render Dashboard][dboard]. - You can use this URL to connect to your instance from your other services in the same region. > If you want to connect to your instance from outside Render (for testing, dev environments, etc.), you also need to [enable external connections](key-value#enabling-external-connections) and add the IP addresses you want to connect from. After you do, you can view your instance's external URL. ## Configure ioredis Next, we'll provide our ioredis client with connection details for our Render Key Value instance. > We strongly recommend storing connection details in [environment variables](configure-environment-variables), such as `REDIS_URL`. ### Connecting via URL We recommend configuring ioredis by passing in the provided internal or external Key Value URL. When used in Blueprints, you can pass this URL to your services using the `fromService` syntax ([docs](blueprint-spec#environment-variables)). ```javascript const Redis = require('ioredis') const { REDIS_URL } = process.env // Internal URL example: // "redis://red-xxxxxxxxxxxxxxxxxxxx:6379" // External URL is slightly different: // "rediss://red-xxxxxxxxxxxxxxxxxxxx:PASSWORD@HOST:6379" const keyValueClient = new Redis(REDIS_URL) keyValueClient.set('animal', 'cat') keyValueClient.get('animal').then((result) => { console.log(result) // Prints "cat" }) ``` ### Setting detailed connection config To explicitly configure ioredis you can use the following examples: #### Internal connection ```javascript const Redis = require('ioredis') // Internal URL, extract the details into environment variables. // "redis://red-xxxxxxxxxxxxxxxxxxxx:6379" const keyValueClient = new Redis({ host: process.env.REDIS_SERVICE_NAME, // Render Key Value service name, red-xxxxxxxxxxxxxxxxxxxx port: process.env.REDIS_PORT || 6379, // Key Value port }) ``` #### External connection ```javascript const Redis = require('ioredis') // External Key Value URL, extract the details into environment variables. // "rediss://red-xxxxxxxxxxxxxxxxxxxx:PASSWORD@HOST:6379" const keyValueClient = new Redis({ username: process.env.REDIS_SERVICE_NAME, // Key Value name, red-xxxxxxxxxxxxxxxxxxxx host: process.env.REDIS_HOST, // Key Value hostname, REGION-kv.render.com password: process.env.REDIS_PASSWORD, // Provided password port: process.env.REDIS_PORT || 6379, // Connection port tls: true, // TLS required when externally connecting to Key Value }) ``` ## Code examples [Full examples for ioredis](https://github.com/render-examples/ioredis) of the above are available in our [Render Examples](https://github.com/render-examples) repo. # Setting Your Elixir and Erlang Versions Elixir version `1.18.4` and Erlang/OTP version `27.0` are the defaults for Render services created on or after *2025-06-12*. You can specify your service's Elixir and/or Erlang/OTP version by setting environment variables: ## Elixir Add an environment variable called `ELIXIR_VERSION` to your service and set its value to a valid version (e.g., `1.14.5`). Supported Elixir versions are [listed below](#supported-elixir-versions). If you don't _also_ specify an Erlang/OTP version, Render automatically downloads an Erlang runtime that's compatible with your chosen Elixir version. ### Supported Elixir versions *Click to show versions* - `1.19.4` - `1.19.3` - `1.19.2` - `1.19.1` - `1.19.0` - `1.18.4` - `1.18.3` - `1.18.2` - `1.18.1` - `1.18.0` - `1.17.3` - `1.17.2` - `1.17.1` - `1.17.0` - `1.16.3` - `1.16.2` - `1.16.1` - `1.16.0` - `1.15.8` ## Erlang/OTP Add an environment variable called `ERLANG_VERSION` to your app and set the value to a valid version (e.g., `24.3.4`). > If you set an Erlang/OTP version, make sure it's [compatible with your Elixir version](https://hexdocs.pm/elixir/1.16.1/compatibility-and-deprecations.html#compatibility-between-elixir-and-erlang-otp)! Supported Erlang/OTP versions are [listed below](#supported-erlangotp-versions). Note that `22.2` is a less recent version than `22.2.8`, because valid versions are based on [tags in the official Erlang repo](https://github.com/erlang/otp/tags). ### Supported Erlang/OTP versions *Click to show versions* - `27.3.4` - `27.3.3` - `27.3.2` - `27.3.1` - `27.3` - `27.2.4` - `27.2.3` - `27.2.2` - `27.2.1` - `27.2` - `27.1.3` - `27.1.2` - `27.1.1` - `27.1` - `27.0.1` - `27.0` - `26.2.5` - `26.2.4` - `26.2.3` - `26.2.2` - `26.2.1` - `26.2` - `26.1.2` - `26.1.1` - `26.1` - `26.0.2` - `26.0.1` - `26.0` - `25.3.2` - `25.3.1` - `25.3` - `25.2.3` - `25.2.2` - `25.2.1` - `25.2` - `25.1.2` - `25.1.1` - `25.1` - `25.0.4` - `25.0.3` - `25.0.2` - `25.0.1` - `25.0` - `24.3.4` - `24.3.3` - `24.3.2` - `24.3.1` - `24.3` - `24.2.2` - `24.2.1` - `24.2` - `24.1.7` - `24.1.6` - `24.1.5` - `24.1.4` - `24.1.3` - `24.1.2` - `24.1.1` - `24.1` - `24.0.6` - `24.0.5` - `24.0.4` - `24.0.3` - `24.0.2` - `24.0.1` - `24.0` - `23.3.4` - `23.3.3` - `23.3.2` - `23.3.1` - `23.3` - `23.2.7` - `23.2.6` - `23.2.5` - `23.2.4` - `23.2.3` - `23.2.2` - `23.2.1` - `23.2` - `23.1.5` - `23.1.4` - `23.1.3` - `23.1.2` - `23.1.1` - `23.1` - `23.0.4` - `23.0.3` - `23.0.2` - `23.0.1` - `23.0` - `22.3.4` - `22.3.3` - `22.3.2` - `22.3.1` - `22.3` - `22.2.8` - `22.2.7` - `22.2.6` - `22.2.5` - `22.2.4` - `22.2.3` - `22.2.2` - `22.2.1` - `22.2` - `22.1.8` - `22.1.7` - `22.1.6` - `22.1.5` - `22.1.4` - `22.1.3` - `22.1.2` - `22.1.1` - `22.1` - `22.0.7` - `22.0.6` - `22.0.5` - `22.0.4` - `22.0.3` - `22.0.2` - `22.0.1` - `22.0` - `21.3.8` - `21.3.7` - `21.3.6` - `21.3.5` - `21.3.4` - `21.3.3` - `21.3.2` - `21.3.1` - `21.3` - `21.2.7` - `21.2.6` - `21.2.5` - `21.2.4` - `21.2.3` - `21.2.2` - `21.2.1` - `21.2` - `21.1.4` - `21.1.3` - `21.1.2` - `21.1.1` - `21.1` - `21.0.9` - `21.0.8` - `21.0.7` - `21.0.6` - `21.0.5` - `21.0.4` - `21.0.3` - `21.0.2` - `21.0.1` - `21.0` - `20.3.8` - `20.3.7` - `20.3.6` - `20.3.5` - `20.3.4` - `20.3.3` - `20.3.2` - `20.3.1` - `20.3` - `20.2.4` - `20.2.3` - `20.2.2` - `20.2.1` - `20.2` - `20.1.7` - `20.1.6` - `20.1.5` - `20.1.4` - `20.1.3` - `20.1.2` - `20.1.1` - `20.1` - `20.0.5` - `20.0.4` - `20.0.3` - `20.0.2` - `20.0.1` - `20.0` - `19.3.6` - `19.3.5` - `19.3.4` - `19.3.3` - `19.3.2` - `19.3.1` - `19.3` - `19.2.3` - `19.2.2` - `19.2.1` - `19.2` - `19.1.6` - `19.1.5` - `19.1.4` - `19.1.3` - `19.1.2` - `19.1.1` - `19.1` - `19.0.7` - `19.0.6` - `19.0.5` - `19.0.4` - `19.0.3` - `19.0.2` - `19.0.1` - `19.0` - `18.3.4` - `18.3.3` - `18.3.2` - `18.3.1` - `18.3` - `18.2.4` - `18.2.3` - `18.2.2` - `18.2.1` - `18.2` - `18.1.5` - `18.1.4` - `18.1.3` - `18.1.2` - `18.1.1` - `18.1` - `18.0.3` - `18.0.2` - `18.0.1` - `18.0` - `17.5.6` - `17.5.5` - `17.5.4` - `17.5.3` - `17.5.2` - `17.5.1` - `17.5` - `17.4.1` - `17.4` - `17.3.4` - `17.3.3` - `17.3.2` - `17.3.1` - `17.3` - `17.2.2` - `17.2.1` - `17.2` - `17.1.2` - `17.1.1` - `17.1` - `17.0.2` - `17.0.1` - `17.0` ## History of default Elixir versions If you don't set an Elixir version for your service, Render's default version depends on when you originally created the service: | Service Creation Date | Default Elixir Version | |---|---| | 2025-06-12 and later | `1.18.4` | | 2024-03-05 | `1.16.1` | | 2023-11-01 | `1.15.6` | | Before 2023-11-01 | `1.9.4` | # Migrating from GitHub Pages Migrating from GitHub Pages to Render is a quick and easy process and gives you much more control over your static site builds and deploys. 1. Create a new *Static Site* on Render and select your GitHub Pages repository. 2. Use the following values during creation: - *Build Command:* `bundle exec jekyll build` - *Publish Directory:* `_site` That's it! Your site will be live on your Render URL as soon as the build finishes. Follow our [custom domains](custom-domains) guide to add your own domains to your site. ## A note on Ruby versions By default, Render uses the latest LTS version of Ruby. It can also automatically detect and install the version of Ruby specified in `.ruby-version` at the root of your project, or in your Gemfile. At the time of writing, GitHub Pages uses ruby version `2.5.3`; you can check the current dependency version on [GitHub Pages' Dependency versions page](https://pages.github.com/versions/). # Changes to Render TLS certificates issued by Let's Encrypt ## What is the change? On September 30th 2021, there will be a change in how older browsers and devices trust Let's Encrypt certificates that Render uses for [TLS on all applications and static sites](tls). This will result in a minor decrease in TLS compatibility for old clients and devices. ## Am I affected? Devices and browsers running up-to-date software will continue working normally. Let's Encrypt has taken steps to maintain support for the vast majority of older devices as well. If you run a large website, or you need to support less common software (particularly non-browser software), please review Let's Encrypt's [documentation](https://letsencrypt.org/docs/dst-root-ca-x3-expiration-september-2021/) about this change. ## What should I do? There is no action required by you. Please reach out to
_These two rules are used by this very documentation site!_
When the path of an incoming request matches a rule's *Source*, Render automatically redirects or rewrites the request to the corresponding *Destination*. For details, see [Rule matching and ordering](#rule-matching-and-ordering).
> *You can't apply redirect/rewrite rules to your domain root.* Each *Source* requires at least one URL path component (such as `/blog`, or even `/`).
## Which action to use?
Set each rule's Action to *Redirect* or *Rewrite* according to your needs:
| Action | Description |
|--------|--------|
| *Redirect* | Instructs the browser (or any other client) to *switch URLs* to the rule's destination via a `301 Moved Permanently` response code. Create a redirect rule if you're moving an existing resource from one path to another (for example, if you move your site's documentation content from `/documentation` to `/docs`). |
| *Rewrite* | *Does not redirect the browser.* Instead, your site serves the content from the rule's destination at the original path. The browser can't detect that content was served from a different path or URL. Create a rewrite rule if: - You want to serve the same content from multiple paths. - Your static site uses a framework with [client-side routing](https://facebook.github.io/create-react-app/docs/deployment#serving-apps-with-client-side-routing) (such as [react-router](https://github.com/ReactTraining/react-router) or [Vue Router](https://router.vuejs.org/)), and you'll handle all requests from a single path like `/index.html`. |
## Rule matching and ordering
*Render does not apply redirect or rewrite rules to a path if a resource exists at that path.* Instead, Render simply serves the resource at that path. This protects against overwriting valid paths with a rule, especially when using [wildcards](#wildcards).
Here's what the full path-matching process looks like:
[diagram]
If this process results in a redirect to another site path, the process repeats with the new path.
## Rule syntax
- *Source* must be a path (not a full URL). This is matched against the path of the incoming request.
- *Destination* can be either a path or a full, publicly accessible URL.
### Basic examples
| Source | Destination |
| ------------------ | -------------------- |
| `/home` | `/` |
| `/blog/index.html` | `/blog` |
| `/web-host` | `https://render.com` |
### Wildcards
Use a *wildcard* (`*`) to match arbitrary strings in a path.
- In *Source*, `*` matches _any_ string that appears starting at that position in the path.
- Specify `/*` to match _all_ paths.
- In *Destination*, `*` applies the _entire string_ captured by the wildcard in *Source*.
| Source | Destination | Example Effect |
| ------ | ------------- | ----------------------------------------- |
| `/*` | `/blog/*` | `/path1/path2` → `/blog/path1/path2` |
| `/*` | `/index.html` | All requests → `/index.html` |
### Placeholders
Use *placeholders* to include specific path components from *Source* in *Destination*:
| Source | Destination | Example Effect |
| ----------------------- | ------------------------- | ---------------------------------------------- |
| `/blog/posts/:postid` | `/blog/:postid` | `/blog/posts/my-post` → `/blog/my-post` |
| `/updates/:month/:year` | `/changelog/:year/:month` | `/updates/03/2024` → `/changelog/2024/03` |
# Setting Your Ruby Version
*Set a different Ruby version in _any_ of the following ways* (in descending order of precedence):
1. Include a `Gemfile.lock` or a `gems.locked` file in the root of your repo that specifies the version to use under `RUBY VERSION`:
```ruby
# Gemfile.lock
RUBY VERSION
ruby 3.3.0
```
You can add this entry to an existing `Gemfile.lock` file or update its value by running:
```shell
bundle update --ruby
```
2. Add a file named `.ruby-version` to the root of your repo. This file contains a single line with the version to use:
```text
3.3.0
```
3. Add a file named `.tool-versions` to the root of your repo. This file can specify versions for multiple languages. To set the Ruby version, add a line like the following:
```text
ruby 3.3.0
```
4. Set the `ruby` directive in your `Gemfile`.
To avoid version mismatches across environments, you can set your Ruby version in the `.ruby-version` file, then read the value from that file in your `Gemfile`:
```ruby
# Gemfile
ruby file: ".ruby-version"
```
## History of default Ruby versions
If you don't set a Ruby version for your service, Render's default version depends on when you originally created the service:
| Service Creation Date | Default Ruby Version |
|---|---|
| 2025-06-12 and later | `3.4.4` |
| 2024-11-24 | `3.3.6` |
| 2024-09-05 | `3.3.5` |
| 2024-07-11 | `3.3.4` |
| 2024-06-13 | `3.3.3` |
| 2024-06-03 | `3.3.2` |
| 2024-04-23 | `3.3.1` |
| 2024-03-18 | `3.3.0` |
| 2023-11-01 | `3.2.2` |
| Before 2023-11-01 | `2.6.8` |
# Specifying a Rust Toolchain
By default, Render uses the latest stable Rust toolchain, but you can specify a different toolchain by adding a [file called `rust-toolchain`](https://rust-lang.github.io/rustup/overrides.html?#the-toolchain-file) at the root of your repo. It should contain a single line specifying the version. For example:
```text
nightly-2020-03-15
```
or
```text
beta
```
You can also use the `RUSTUP_TOOLCHAIN` environment variable and set the value to a valid version. The environment variables overrides the version in toolchain files.
> If you override the toolchain in your build command with cargo +nightly... the specified toolchain must already be installed. You can install new toolchains using `rustup` as part of your build command.
Learn more about [Rust toolchains](https://rust-lang.github.io/rustup/concepts/toolchains.html).
# HTTP Headers for Static Sites
Since static sites don't have a server-side component that can inject custom [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) in responses, Render lets you define response headers for your static sites in your [dashboard][dboard].
## Header Syntax
The *header path* must be a relative path without the domain. It will be matched with all custom domains attached to your site.
You can use *wildcards* to match arbitrary request paths.
| Path | Effect |
| ----------- | ---------------------------------------------------------------------------- |
| `/*` | Matches all request paths. |
| `/blog/*` | Matches `/blog/`, `/blog/latest-post/`, and all other paths under `/blog/` |
| `/**/*` | Matches `/blog/`, `/assets/`, and all other paths with at least two slashes. |
| `/*.css` | Matches `/tokens.css` and `/mode.css`, but not `/assets/theme.css` |
| `/**/*.css` | Matches `/assets/theme.css` but not `/tokens.css` |
The *name* is the *case-insensitive* name for the header. Examples include:
- `Cache-Control`
- `X-Frame-Options`
- `Referrer-Policy`
The *value* of the header is sent as-is in the response. Examples include:
- `public, max-age=86400`
- `DENY`
- `same-origin`
The header key is normalized and the value is appended to it to form the response:
- `cache-control: public, max-age=86400`
- `x-frame-options: DENY`
- `referrer-policy: same-origin`
# Deploy an AI Chatbot with LangChain and MongoDB
> This tutorial is featured by [MongoDB](https://www.mongodb.com/), a Render partner.
Deploy an AI chatbot that uses Retrieval-Augmented Generation (RAG) powered by data from PDFs you upload.
You'll follow steps to:
1. Create a Render web service
2. Connect the Render web service to a MongoDB Atlas instance
3. Enable vector search by adding a vector index to your Atlas instance
For general guidance on connecting your Render services to MongoDB Atlas, see [this article](connect-to-mongodb-atlas).
# Setting Your uv Version
| Current default uv version |
|--------|
| *`0.7.12`* |
[uv](https://docs.astral.sh/uv/) is a packaging and dependency manager for Python. Render automatically adds uv to your Python service's runtime if your project's root directory includes a `uv.lock` file.
To specify a uv version, set your service's `UV_VERSION` [environment variable](configure-environment-variables) to any version number that's compatible with your [Python version](python-version).
## History of default uv versions
| Service Creation Date | Default uv Version |
|---|---|
| 2025-06-12 and later | `0.7.12` |