Migrate from Heroku to Render
This guide 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.
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.
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 |
Worker Process (within a Heroku app) | Background Worker |
Dyno | An instance of your service on Render |
Heroku Postgres | Render PostgreSQL |
Heroku Redis | Render Redis |
Heroku Scheduler | Cron Job |
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.
The CLI plugin will not modify your Heroku app. It only performs read operations.heroku plugins:install @renderinc/heroku-import
Run CLI Plugin
The CLI plugin will read information about your app and its add-ons and create three files:
.render-buildpacks.json
specifies the set of application capabilities, wrapped up in buildpacks, that your application needs. The Render CLI sources it from the state of your currently-running application on Heroku.Dockerfile.render
allows you to build a Docker image to deploy on Render.render.yaml
is infrastructure as code that specifies to Render how to run your service and any Postgres or Redis services that your application needs.
Here is what the process looks like. Run it from the root of the repository containing your app’s code.
heroku render:import --app salty-waters-73797
=== 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)
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 .render-buildpacks.json
, Dockerfile.render
, and render.yaml
will be created for you and the following instructions will be shown.
=== 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 source control.
Excluded Environment Variables
DATABASE_URL
HEROKU_
KEY
PASSWORD
REDIS_URL
REDIS_TLS_URL
SECRET
TOKEN
Add .render-buildpacks.json
, Dockerfile.render
and render.yaml
to Source Control
The CLI plugin has now created three files: .render-buildpacks.json
, Dockerfile.render
, and render.yaml
. To review:
.render-buildpacks.json
specifies the set of application capabilities, wrapped up in buildpacks, that your application needs. The Render CLI sources it from the state of your currently-running application on Heroku.Dockerfile.render
allows you to build a Docker image to deploy on Render.render.yaml
, also known as a Blueprint, is infrastructure as code that specifies to Render how to run your service and any Postgres or Redis services that your application needs.
Now, add these three files to source control with the following commands.
git add .render-buildpacks.json Dockerfile.render render.yaml
git commit -m 'Prepare app for deploy to Render'
git push origin
Step 2: Create 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 will create a instance type 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 above.
Review the instance type 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 with names containing values indicating they may contain secrets.
To create or update environment variables using the Render Dashboard,
- Select Dashboard on the left
- Select the service you just created from the list
- 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
Migrating from Heroku? We’re previewing an upcoming tool for low-downtime PostgreSQL migration and are looking for organizations with a large (50+ GB) Heroku Postgres database to migrate. We’ll work with selected organizations to help ensure a successful, speedy migration.
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 you 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
If your database is larger than 20GB or under heavy load, use Heroku’s instructions 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.
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 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.