Skip to content

Migrate from Heroku to Coherence

This guide shows you how to easily migrate your application from Heroku to Coherence.

By running your app in your own cloud account on Amazon Web Services (AWS) or Google Cloud Platform (GCP), you get the compliance, cost, and customization benefits that only the large public cloud providers can offer. Read more about Coherence vs. platform-as-a-service (PaaS) provider hosting here.

Coherence offers the features you love on Heroku, like built-in CI/CD and preview environments, while also delivering a great developer experience with a user-friendly developer portal and CLI. When you use Coherence, you don't need to be a DevOps expert to manage a world-class deployment platform - leave that part to us. Additionally, you can use your cloud credits with Coherence, making it the perfect choice for startups.

What You'll Learn

This guide will show you how to:

  1. Prepare an application deployed on Heroku for deployment on Coherence
  2. Deploy the application on Coherence
  3. Migrate the data from your Heroku database to Coherence
  4. Transfer your domain from Heroku to Coherence

Prerequisites

To follow along, you'll need:

1. Prepare your Heroku application for migration

Coherence gives you flexible options for building and deploying your application.

If you don't have a Dockerfile, Coherence will automatically use Nixpacks to build your container. This means you don't need to make any changes to your application structure.

Option B: Use an existing Dockerfile

If you've been using the Heroku container registry with a Dockerfile, Coherence will use that Dockerfile to deploy your application. No additional preparation is needed.

Option C: Write a Dockerfile (if necessary)

If your application uses a Heroku Procfile and you prefer not to use Nixpacks, you'll need to write a Dockerfile for your application. For more information on writing a Dockerfile, see the Dockerfile reference documentation.

Save your startup command

Regardless of which option you choose, you'll need to note the command used to start your application. You can find this in your Procfile or Dockerfile, or by checking the Resources tab in your Heroku dashboard under the Eco Dynos heading.

For example, your startup command might look like this:

web: npm run start

You'll need this command when configuring your service in Coherence.

2. Deploy your application on Coherence

Now that your code is prepared, let's set up your application on Coherence.

Create a new application

  1. In the Coherence dashboard, click New application
  2. Give the application a name
  3. Select Google Cloud as the provider and Cloud Run as the architecture
  4. Click Continue

Create a collection

Collections in Coherence allow you to organize environments.

  1. On the application's landing page, click Create collection
  2. Give the collection a name
  3. Click Create Collection

Configure an environment

  1. In the collection, click New Environment
  2. Give the environment a name
  3. Select the appropriate environment type (Staging is recommended for initial testing)
  4. Click Create

Add Coherence services

Services in Coherence are loosely equivalent to web dynos in Heroku. Here's how to set them up.

Create a backend service

  1. Click the environment name to enter the environment homepage
  2. Go to the Services tab
  3. Click New service and select the framework for your project under Container
  4. Configure the service:
  5. Name: Give the service a name, like "backend"
  6. Start Command: Enter the command you saved earlier (e.g., npm run start)
  7. Enter "/" under URL path
  8. Container source: Choose Repository
  9. Click Add one under Repo
  10. Paste in the link to your GitHub code repository
  11. Enter "/" under Context
  12. If you're using a Dockerfile, enter "Dockerfile" under Dockerfile. Otherwise, leave it blank to use Nixpacks
  13. Select your track branch (for example, main)
  14. Click Create service

After creating the service, add the necessary environment variables in the Variables tab. You can bulk import variables using the Coherence UI. The Coherence CLI offers environment variable management capability for scripting.

Create a database service

  1. In the Services tab, click New service and select Postgres (or equivalent database)
  2. Configure the database:
  3. Name: Give the service the same name as your application's database
  4. Engine: Enter "postgres"
  5. Version: Choose the appropriate version
  6. Click Create service

Connect to your cloud provider

Follow the steps in our Google Cloud guide or AWS guide to connect Coherence to your cloud account.

Start a provisioning task

When Coherence has been granted access to your cloud account, submit a provisioning task so that Coherence can automatically set up and manage the necessary cloud resources for your collection.

  • Select the Provision Tasks tab for the collection
  • Click the Submit button to submit a provisioning task
  • Click the Submit new task button

Coherence will automatically provision infrastructure for your project based on your service requirements. Wait for this step to complete before moving on. It should take several minutes.

Start a build and deploy pipeline

  1. Go to the Deployments tab for the environment
  2. Click New deployment
  3. Select the branch and commit to build from
  4. Click Submit deployment to start the build and deploy process

View your deployed application

Once the build is complete:

  1. In your Coherence dashboard, navigate to your environment
  2. Look for the Domains section and find the provided URL
  3. Click the URL to open your deployed application in a new browser tab

3. Migrate the data

This is a crucial step in the migration process. Don't hesitate to contact the Coherence team if you need assistance.

Export data from Heroku

  1. In your Heroku dashboard, go to the Settings tab
  2. In the Config Vars section, copy the DATABASE_URL value A screenshot shows the "Config Vars" section of the Heroku settings page.
  3. On your local machine, install pg_dump
  4. Use pg_dump to export your data:
pg_dump "your-connection-string" > heroku_db_dump.sql

Choose a migration method

You can migrate data to Coherence in two ways:

  1. Using the Coherence CLI (cocli), which includes a bastion to a private IP in your VPC
  2. Migrating directly to your cloud database using a public IP

Choose the method you prefer below.

Set up a CNC toolbox

Set up a CNC toolbox to interact with your Coherence environment from your local machine:

gcloud auth application-default login
gcloud auth login

Start a toolbox

First, set up authentication.

  • In the Coherence dashboard, navigate to your profile
  • Click Create token
  • Give the token a name and select an expiration period
  • Click Create token
  • Copy the token value
  • Run the following command on your local machine with your access token:
export COHERENCE_ACCESS_TOKEN="your-access-token-here"

Next, set your app ID and collection ID to variables.

In your terminal, add your app name and collection name to the command below:

app_id=$(cocli apps list | jq '.[] | select(.title=="Your App Name") | .id')

collection_id=$(cocli collections list -a $app_id | jq '.data[] | select(.name=="your-collection-name") | .id')

To start a toolbox, replace main with your environment name in the following command:

cocli cnc -c $collection_id -- toolbox start main --proxy-only

Keep the toolbox running while you migrate the data in a new terminal.

Migrate the data to the Coherence project

To import your data to your new Coherence-managed database:

  • Open a new terminal in the folder containing the heroku_db_dump.sql file
  • Get the psql database connection string from Coherence by copying the value of the DATABASE_URL variable found in the Variables tab on your environment homepage
  • Run the following command, replacing <database-connection-string> with your database connection string and path/to/heroku_db_dump.sql with the path to your migration file:
psql -d <database-connection-string> < path/to/heroku_db_dump.sql

To migrate your data directly to GCP, first authorize your public IP.

  • Get your public IP. Find your public IP here.
  • Navigate to your GCP console
  • Navigate to SQL in the left menu
  • Navigate to Connections and open the Networking tab
  • Scroll down to Authorized networks
  • In New network*, give your network a name and add your public IP address in the Network* field
  • Click Add network, then click Save at the bottom of the page

A screenshot shows a "New network" dialog in the "Connections" tab on the Google Cloud SQL dashboard.

Connect to your Cloud SQL database on your local machine with the following command:

psql -d <database-connection-string> < path/to/heroku_db_dump.sql

Verify the data migration

Check your application to ensure your data has been successfully migrated.

4. Migrate the domain

The final step is to update your domain settings to point to your Coherence-hosted application.

Remove the domain from Heroku

  1. In your Heroku project settings, navigate to the Domains section
  2. Remove the custom domain from your Heroku project

Change DNS settings for the domain

  1. Log in to your domain registrar's dashboard
  2. In the Coherence dashboard, navigate to your environment homepage and select the Custom domains tab
  3. Add your custom domain to the Domain field
  4. Copy the provided DNS record and add it to your domain registrar's settings
  5. Click Add domain to save the configuration

A screenshot shows the domain under the "Add a custom domain" header in the "Custom domains" tab of an environment homepage on Coherence.

Wait for DNS propagation (up to 48 hours).

Once DNS propagation is complete, visit your domain to verify that your website is accessible and your migrated data is functioning correctly.

Conclusion

Congratulations! You've successfully migrated your application from Heroku to Coherence. Enjoy the benefits of running your application on your own cloud infrastructure while maintaining the ease of use you're accustomed to with PaaS providers.

If you encounter any issues or have questions during the migration process, don't hesitate to reach out to the Coherence support team. We're here to ensure your migration is smooth and successful.