Migration Guide: Heroku to Render
Tags: heroku, webdev, devops
Published: 2022-08-25 20:43:00

[This guide](https://render.com/docs/migrate-from-heroku) will help you migrate a Heroku app, Heroku Postgres database, and Heroku Redis instance to Render. Using Render to run your web services and databases is very similar to running them on Heroku. Additionally, many users have found that Render saves them money and provides additional functionality not available from Heroku. Read more about the [differences between Render and Heroku](/render-vs-heroku-comparison).

This guide and associated Heroku CLI plugin covers most migration use cases. It supports migrating a Heroku app and its Heroku Postgres and Heroku Redis add-ons. You may continue using other Heroku add-ons while your app is running on Render by copying over the appropriate environment variables -- e.g., if you are using Heroku's Sengrid add-on, set `SENDGRID_USERNAME` and `SENDGRID_PASSWORD` in the Render Dashboard. Please contact us at support@render.com if you experience any problems migrating from Heroku to Render.

### Requirements

- Heroku app is using one of Heroku's [official buildpacks](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks)[^1]
- Heroku app is not using multiple buildpacks[^2]

## Migration Steps

1. [Generate a `Dockerfile.render` and `render.yaml` using Render's Heroku CLI Plugin](#step-1-generate-a-dockerfilerender-and-renderyaml)
2. [Create Resources on Render](#step-2-create-resources-on-render)
3. [Configure Environment Variables](#step-3-configure-environment-variables)
4. [Copy Data From PostgreSQL](#step-4-copy-data-from-postgresql)
5. [Update DNS Configuration](#step-5-update-dns-configuration)

[^1]: If you would like to migrate a Heroku app to Render that is not using an official Heroku buildpack please contact us at support@render.com for assistance.

[^2]: We are working on supporting migration of Heroku apps that use multiple buildpacks.

## Concept Mapping

Before you start the migration, review the following table to understand how some Heroku concepts map to Render concepts.

| Heroku                               | Render                                                          |
|--------------------------------------|-----------------------------------------------------------------|
| Web Process (within a Heroku app)    | [Web Service](/docs/web-services)             |
| Worker Process (within a Heroku app) | [Background Worker](/docs/background-workers) |
| Dyno                                 | An instance of your service on Render                           |
| Heroku Postgres                      | [Render PostgreSQL](/docs/databases)          |
| Heroku Redis                         | [Render Redis](/docs/redis)                   |
| Heroku Scheduler                     | [Cron Job](/docs/cronjobs)                    |
| Config Vars                          | Environment Variables                                       |

## Step 1: Generate a `Dockerfile.render` and `render.yaml`

### Install Render's Heroku CLI Plugin

Render has created a plugin for the Heroku CLI to reduce some of the manual migration steps. Install the plugin with the following command.

<info-block>
The CLI plugin will <strong>not</strong> modify your Heroku app. It only performs read operations.
</info-block>

```shell
heroku plugins:install @renderinc/heroku-import
```

### Run CLI Plugin

The CLI plugin will read information about your app and its add-ons and create two files: `Dockerfile.render` and `render.yaml`. Here is what the process looks like. Run it from the root of the repository containing your app's code.

You will then be prompted to select the Heroku Postgres and Heroku Redis add-ons you would like to migrate to Render. After making your selections, a `Dockerfile.render` and `render.yaml` will be created for you, and instructions will be shown.

#### Excluded Environment Variables

- `DATABASE_URL`
- `HEROKU_`
- `KEY`
- `PASSWORD`
- `REDIS_URL`
- `REDIS_TLS_URL`
- `SECRET`
- `TOKEN`

### Add `Dockerfile.render` and `render.yaml` to Source Control

The CLI plugin has now created two files: `Dockerfile.render` and `render.yaml`. The `Dockerfile.render` defines how to build your app on Render using a Heroku buildpack. The `render.yaml` is Render's [Infrastructure-as-Code](/docs/infrastructure-as-code) file. It can be used to define multiple services and databases running on Render and their relationship to each other.

Now, add these two files to source control with the following commands.

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

## Step 2: Create Resources on Render

From the [Render Dashboard](https://dashboard.render.com), select **New +** and then **Blueprint**. Connect your [GitHub](/docs/github) or [GitLab](/docs/gitlab) account to Render if you haven't already, and then search for and select your repository.

Render will create a plan to build and deploy your service along with a Render PostgreSQL database and Render Redis service if your Heroku app was using these and you selected them for import in the [Run CLI Plugin step](#run-cli-plugin) above.

Review the plan and click **Apply**, and 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 contact us at support@render.com. We're here to help!

## Step 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 [excluded environment variables](#excluded-environment-variables) with names containing values indicating they may 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)

## Step 4: Copy Data from PostgreSQL

### 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.

<info-block>
This data migration process requires some downtime.
</info-block>

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

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

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

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

```shell
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.

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

<info-block>

If your database is larger than 20GB or under heavy load, use [Heroku's instructions](https://help.heroku.com/7U1BTYHB/how-can-i-take-a-logical-backup-of-large-heroku-postgres-databases) to create a backup of your data. After that has completed, you can use the same `pg_restore` command above to import the data to your Render PostgreSQL database.

Consider using the `--jobs` flag available to both the `pg_dump` and `pg_restore` commands to reduce the time required for backup and restore.

</info-block>

## Step 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](/docs/custom-domains#configuring-dns-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.

<br>