How Deploys Work
Render makes deploying your application as easy as pushing your code to source control.
Automatic Git deploys
By default, Render automatically deploys your GitHub- or GitLab-backed service whenever you push to its linked branch (such as by merging a pull request).
Image-backed services (services that pull a Docker image from a container registry) don’t perform these automatic deploys. See details.
You can skip an auto-deploy for a particular commit or even disable auto-deploys entirely for your service.
Skipping an auto-deploy
Certain changes to your codebase might not merit a new deploy, such as edits to a README
file. In these cases, you can include a skip phrase in your Git commit message to prevent the change from triggering an auto-deploy:
git commit -m "[skip render] Update README"
The skip phrase is one of [skip render]
or [render skip]
. You can also use one of the following in place of render
:
deploy
cd
When an auto-deploy is skipped, a corresponding entry appears on your service’s Events page:
If you configure build filters for your repo, Render deploys your service only if there are changes to particular files. This method of skipping an auto-deploy doesn’t require a skip phrase. See Specifying Build Filters.
Disabling auto-deploys
If you always want to trigger deploys manually, you can disable auto-deploys in the Render Dashboard. Go to your service’s Settings page and set Auto-Deploy to No:
Don’t forget to save your changes!
Deploy steps
With each deploy, Render proceeds through the following commands for your service:
*Consumes pipeline minutes while running. View your usage.
You specify these commands as part of creating your service in the Render Dashboard. You can modify these commands for an existing service from its Settings page:
Each command is described below.
If one of these commands fails, the entire deploy fails and any remaining commands do not run. Your service continues running its most recent successful deploy (if any), with zero downtime.
Build command
Performs all compilation and dependency installation that’s necessary for your service to run. It usually resembles the command you use to build your project locally.
This command consumes pipeline minutes while running. You receive a free allotment of pipeline minutes each month and can purchase more as needed. View your usage.
Example build commands for each runtime
Runtime | Example Build Command(s) |
---|---|
Node.js | yarn , npm install |
Python | pip install -r requirements.txt |
Ruby | bundle install |
Go | go build -tags netgo -ldflags '-s -w' -o app |
Rust | cargo build --release |
Elixir | mix phx.digest |
Docker | You can’t set a build command for services that use Docker. Instead, Render either builds a custom image based on your Dockerfile or fetches a specified image from your container registry. |
Pre-deploy command
If defined, this command runs after your service’s build finishes, but before that build is deployed. Recommended for tasks that should always precede a deploy but are not tied to building your code, such as:
- Database migrations
- Uploading assets to a CDN
The pre-deploy command is available for paid web services, private services, and background workers.
If you don’t define a pre-deploy command for a service, Render proceeds directly from the build command to the start command.
This command consumes pipeline minutes while running. You receive a free allotment of pipeline minutes each month and can purchase more as needed. View your usage.
Start command
Render runs this command to start your service when it’s ready to deploy.
Example start commands for each runtime
Runtime | Example Start Command(s) |
---|---|
Node.js | yarn start , npm start , node index.js |
Python | gunicorn your_application.wsgi |
Ruby | bundle exec puma |
Go | ./app |
Rust | cargo run --release |
Elixir | mix phx.server |
Docker | By default, Render runs the CMD defined in your Dockerfile. You can specify a different command in the Docker Command field on your service’s Settings page. |
Canceling a deploy
You can cancel an in-progress deploy from the Render Dashboard.
-
Go to your service’s Events page and click the word Deploy in the corresponding event entry.
- This opens the deploy’s details page.
-
Click Cancel deploy:
Restarting a service
If your service is misbehaving, you can restart it from the service’s page in the Render Dashboard. Click Manual Deploy > Restart service:
Note the following about restarting a service:
- When you restart your service, Render actually deploys a completely new instance and swaps over to it when it’s ready. The original running instance is then deprovisioned.
- This makes restarting a zero-downtime action, similar to other deploys.
- If you restart a scaled service, Render performs a restart for every instance.
- If you restart a service, the new instance uses the same configuration as the original instance, including values of environment variables.
- This means that if you’ve recently updated your service’s configuration but haven’t redeployed since then, restarting will not cause your service to incorporate those updates.
Zero-downtime deploys
Render makes sure your applications never go down, even when your build breaks.
We also restart your apps automatically if they become unresponsive or start returning errors. We do this by utilizing user-defined health checks, described below.
Adding a persistent disk to your service disables zero-downtime deploys for it. See details.
Health checks
The core primitive behind health checks is a path in your app (say /healthz
) that returns a successful HTTP response if your app is healthy, and a failure response if it isn’t.
What you return on your health check path is up to you, but we recommend running quick sanity checks (like a simple database query) and returning an “OK” 200
response or an empty 204
response if the app is healthy.
A health check is considered successful when the health check path returns a response code between 200
and 399
. Any other code (or a timeout) causes it to fail.
How Render uses health check paths
Defining health check paths is optional, but if you define a health check path for your app (and you really should), here’s how we use it for zero-downtime deploys:
-
When your app is first deployed, we issue a
GET
request to your health check path after running your start command. If your service has verified custom domains, we will set the hostname to one of your custom domains. If not, we will set the hostname to your service’s default onrender.com domain.Your deploy is marked
live
if the health check passes, which means it returns an HTTP response code between 200 and 399. Any other response code (or a timeout) results in a deploy failure. -
When a new version of your app is deployed, we keep the existing version up and continue to send user requests to it. At the same time, we bring up a new instance of your app with the new version. We then issue health check requests on the new instance, and depending on the response, do one of two things:
-
If your app fails to return a successful response (for example, returns only
403
or500
error codes) within 15 minutes, we consider the new version unhealthy, and mark the deploy failed. Nothing changes as far as your users are concerned, because your existing version is still around and serving requests. You can now start figuring out why the health check failed by looking at the logs. -
If your app returns a successful response (for example, a
200
response code) within 15 minutes, we mark the deploylive
and start directing user requests to the shiny new version of your app. -
After 60 seconds of your new service handling requests, we terminate the old version at this point by sending your app a
SIGTERM
signal. Most web servers automatically interceptSIGTERM
and shut down gracefully. There is a grace period of 30 seconds to shut everything down. If your app is still up after 30 seconds, it is shut down via aSIGKILL
signal.
This is how you get zero downtime deploys without needing to maintain two versions of your app at all times.
-
-
After your app is live, we continue to monitor its health by running a health check every few seconds. If your app starts failing the health check, we restart it automatically. As with most software, this tends to fix to the issue, but if it doesn’t we mark the deploy failed and send you a notification so you can fix things.
This is how we achieve maximum uptime for your app, with minimal effort on your part. Right now, health checks are available to use for all web services, including Docker deployments. If you need to use health checks for other service types, please reach out to us in our community.