Migrate from Heroku to Render

This guide helps you move your Heroku apps and datastores to Render. Migration is straightforward, and many developers find that running on Render reduces costs and enables capabilities that aren’t available on Heroku.

The steps in this guide support the majority of Heroku apps, along with their Heroku Postgres and Heroku Key-Value Store add-ons.

You can continue using other Heroku add-ons while your app is running on Render by copying over the appropriate environment variables. For example, if you’re using Heroku’s Sengrid add-on, set SENDGRID_USERNAME and SENDGRID_PASSWORD for your new service in the Render Dashboard.

If you need any help with your migration, please reach out to our support team in the Render Dashboard.

Concept mapping

Most Heroku concepts map cleanly to comparable functionality on Render:

1. Generate config files for Render deployment

To simplify moving your app to Render, we’ll create three configuration files in your app’s repository:

To achieve this, we’ll use a Render-provided plugin for the Heroku CLI. This plugin reads your Heroku app’s configuration and generates the corresponding Render config.

Install the Heroku CLI plugin

Run the following command to install Render’s heroku-import plugin for the Heroku CLI:

heroku plugins:install @renderinc/heroku-import

Run the CLI plugin

From the root of the repository containing your app’s code, run the following command, replacing <HEROKU_APP_NAME> with the name of your Heroku app:

heroku render:import --app <HEROKU_APP_NAME>

The plugin prompts you to select any Heroku Postgres and Heroku Redis add-ons you want to migrate to Render:

=== Gathering information about Heroku app
Verifying app is using a single, official Heroku buildpack... ✔️
Getting stack image... heroku-20
Getting and translating plan... Heroku Hobby $7/mo --> Render Starter $7/mo
Getting instance count... 1
Getting custom domains... 1 custom domain(s)
Getting environment variables... 11 environment variable(s)
Getting add-ons... 3 add-on(s)

? Select addons to import. (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ postgresql-infinite-25060 using hobby-dev plan
 ◯ redis-perpendicular-19613 using hobby-dev plan
 - sendgrid-round-75662 using starter instance type (Cannot import)

After you make your selections, the plugin generates the three aforementioned configuration files in your repository root. It also outputs a message with instructions on how to complete the migration:

=== Environment variables excluded from render.yaml
The following environment variables were not included in the generated
  render.yaml file because they potentially contain secrets. You may need to
  manually add them to your service in the Render Dashboard.

- DATABASE_URL: postgresql://jfgygkqpttdlqz:7573fb63145ea4727585c2caa2828c18b02e7fb32a25f45d9f3e2a0a294eca55@ec2-67-202-36-228.compute-1.amazonaws.com:5432/d39e0kf7r3grvv
- REDIS_TLS_URL: rediss://:p1b6f029e082ff2038f1dc7f10ea8379db64f5d0cff7ac26efcb399bfda809714@ec2-3-232-249-112.compute-1.amazonaws.com:12490
- REDIS_URL: redis://:p1b6f029e082ff2038f1dc7f10ea8379db64f5d0cff7ac26efcb399bfda809714@ec2-3-232-249-112.compute-1.amazonaws.com:12489
- SECRET_KEY_BASE: 41af19d9626b006f815342a9e7fe7a53bd22f0870b77e286c3a78866e8d619de3ce365de5fe32d00571818f44a24cae0969aa5963b8cc15cf8c076555916fb7d
- SENDGRID_PASSWORD: isomynvn7190

=== Follow these steps to complete import of service(s) and database(s) to Render
1. Add, commit, and push the generated render.yaml and Dockerfile.render to GitHub/GitLab/Bitbucket.
2. Go to https://dashboard.render.com/select-repo?type=iac
3. Search for and select this repository.
4. Verify the instance type showing the resources that Render will create, and
   then click 'Create New Resources'.
5. After the resources are deployed, you may need to manually add
   the above environment variables to your Web Service in the Render Dashboard.
   They were not included in the generated render.yaml because they potentially
   contain secrets.

Notice in the output above that environment variable names containing the following are excluded from the generated render.yaml to reduce the chance that secrets like passwords and API keys are added to version control.

Excluded environment variables

• DATABASE_URL
• HEROKU_
• KEY
• PASSWORD
• REDIS_URL
• REDIS_TLS_URL
• SECRET
• TOKEN

Commit config files to version control

With the three configuration files generated, commit them to your repository:

git add .render-buildpacks.json Dockerfile.render render.yaml
git commit -m 'Prepare app for deploy to Render'
git push origin

2. Deploy resources on Render

In the Render Dashboard, click New > Blueprint. Connect your GitHub, GitLab, or Bitbucket account to Render if you haven’t already, and then search for and select your repository.

Render creates a new service to run your application, along with any PostgreSQL databases and Redis instances that you selected for import when you ran the CLI plugin.

Review the service’s instance type and other details, then click Apply. Render will create your resources.

If all resources were created successfully, continue to the next step. If there was an error you cannot resolve, please reach out to our support team in the Render Dashboard.

3. Configure environment variables

You may need to manually create environment variables that contain secrets like passwords or API tokens using the Render Dashboard. The CLI plugin excludes environment variables with names that indicate they contain secrets.

To create or update environment variables using the Render Dashboard,

1. Select Dashboard on the left
2. Select the service you just created from the list
3. Select the Environment tab and create or update environment variables (check the CLI plugin output if you’d like to copy from your Heroku Config Vars)

4. Copy data from PostgreSQL

If you have created a Render PostgreSQL database, you may want to copy the data from your Heroku Postgres database to Render.

Put your Heroku app into maintenance mode so that no new data is written to the database during the copy. <HEROKU APP NAME> is the Heroku app that owns the Heroku Postgres add-on.

heroku maintenance:on --app <HEROKU APP NAME>

Create a backup of the data in your Heroku Postgres database.

heroku pg:backups:capture --app <HEROKU APP NAME>

Download the backup. This will download a file named latest.dump to your local computer.

heroku pg:backups:download --app <HEROKU APP NAME>

Import latest.dump into your Render PostgreSQL database. The value for <EXTERNAL CONNECTION STRING> can be found on the Render Dashboard page for your database.

pg_restore --verbose  --no-acl --no-owner -d <EXTERNAL CONNECTION STRING> latest.dump

5. Update DNS configuration

If your Heroku app is using a custom domain, follow the instructions to update your DNS configuration to point to Render instead of Heroku. Note that some downtime may be required between when your DNS changes propogate and when Render provisions a TLS certificate for your domain.