Migrate from Heroku to Koyeb

Introduction

This guide explains how to seamlessly migrate and deploy your Heroku apps to the Koyeb serverless platform.

If you are running on the Heroku free tier, you probably noticed Heroku will stop offering free plans starting November 28, 2022. At Koyeb, we are offering a generous free tier allowing hobbyists from all around the world to run their apps with minimal costs on a simple, robust, and global platform.

By deploying your Heroku apps on Koyeb, you benefit from native autoscaling, automatic HTTPS (SSL), auto-healing, custom domains, service metrics, and global load-balancing across our edge network with zero configuration.

Koyeb builds system natively supports Heroku Buildpacks making the build and deployment experience on Koyeb nearly the same as you get on Heroku. If a Procfile exists in the repository containing your app code, Koyeb will automatically detect it and use the commands defined inside the file to run your application so the configuration efforts to migrate on Koyeb are minimal.

If you are looking for more details about how the Koyeb platform compares to Heroku, we strongly recommend you to check out our Koyeb vs Heroku comparison.

The video shows how to migrate a Node.js API from Heroku to Koyeb using git-driven deployment.

What is Koyeb?

Koyeb is a serverless platform allowing developers and businesses to deploy full-stack applications around the world with high performance and a developer-centric experience. We aim to dramatically reduce deployment time and operational complexity by removing server and infrastructure management for businesses and developers.

Requirements

To successfully follow and complete this guide and migrate your Heroku apps to Koyeb you need:

• An existing Heroku app deployed and running
• A Koyeb account to deploy and run your Heroku app on Koyeb
• A GitHub repository containing your Heroku code
• The Heroku CLI installed on your machine
• The Koyeb CLI installed on your machine

Steps

To migrate your first Heroku app to Koyeb, you need to complete the following steps:

1. Create a new Koyeb app and service
2. Import your Heroku environment variables
3. Configure a custom domain
4. Database migration (optional)

Once these steps are completed, you will have your previously running Heroku app migrated on Koyeb with a custom domain configured.

Create a new Koyeb app and service

The first step to migrating a Heroku app to Koyeb is to create a new Koyeb app and service to deploy and run your application.

In this section, we will cover two methods to perform these operations using:

1. The Koyeb control panel
2. The Koyeb CLI

Using the Koyeb control panel

Go to the Overview tab of the Koyeb control panel and click the Create Web Service button to begin:

1. Choose GitHub as the deployment method. If this is your first time, click the Install GitHub app button to install the Koyeb GitHub app. This will allow Koyeb to access your GitHub repositories and automatically redeploy your application when code changes are pushed.
2. Select the repository containing the Heroku application to migrate to Koyeb.
3. In the Exposed ports section, change the export port to your application port.
4. Choose a name for your App and Service, for example heroku-app-to-koyeb, and click Deploy.

You will automatically be redirected to the Koyeb App page where you can follow the progress of your application deployment. In a few seconds, once your app is deployed and healthy, click on the Public URL ending with koyeb.app.

Everything should work now. Your application is running on Koyeb and benefits from native autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network.

Using the Koyeb CLI

In the previous section, we discovered how to migrate a Heroku app to Koyeb using the Koyeb control panel. We will now showcase how to perform this operation using the Koyeb CLI.

Before getting started using the CLI, make sure you are logged in and have the Koyeb GitHub app installed.

Then, in your terminal, update the values with your own and run the following command to create a new Koyeb app and service:

koyeb app init heroku-app-to-koyeb \
  --git github.com/<YOUR_GITHUB_USERNAME>/<YOUR_GITHUB_REPOSITORY> \
  --git-branch <YOUR_REPOSITORY_BRANCH_NAME> \
  --ports 8080:http
  --routes /:8080

The command below will create a new Koyeb app and service with the name heroku-app-to-koyeb and deploy the selected GitHub repository on Koyeb.

If your application is listening to another port than 8080, simply change the port value with the port your application is listening to.

App
id        	8736fa0a
name      	heroku-app-to-koyeb
domains   	["heroku-app-to-koyeb-my-org.koyeb.app"]
created_at	29 Aug 22 12:42 UTC

Service
ID      	APP                	NAME               	VERSION	STATUS  	CREATED AT
e8d79368	heroku-app-to-koyeb	heroku-app-to-koyeb	0      	STARTING	29 Aug 22 12:42 UTC

Et voilà, your application is being provisionned and deployed on Koyeb. Within a few seconds, once your app is built and deployed, you will be able to access it by clicking the Koyeb public domain ending with koyeb.app.

Import your Heroku environment variables

If the Heroku app to migrate uses environment variables, you can import them to Koyeb quickly using the Heroku and Koyeb CLI.

The script below retrieves your Heroku app environment variables running heroku config -a <YOUR_HEROKU_APP_NAME> --json and updates your Koyeb service to add them.

HEROKU_CONFIG=$(heroku config -a <YOUR_HEROKU_APP_NAME> --json)
KOYEB_APP_NAME="<YOUR_KOYEB_APP_NAME>"
KOYEB_SERVICE_NAME="<YOUR_KOYEB_SERVICE_NAME>"

ENVS=""

for key in $(echo $HEROKU_CONFIG | jq -r '. | keys[]'); do
    ENVS+="--env $key=$(echo $HEROKU_CONFIG | jq -r ".[\"$key\"]") "
done

koyeb service update $KOYEB_APP_NAME/$KOYEB_SERVICE_NAME $(echo $ENVS)

Once the update is completed, your Koyeb service will be redeployed automatically and environment variables will be exposed at build and runtime.

Configure a custom domain

By default, when creating an app on Koyeb, you get an auto-generated domain name to access your app. Koyeb allows you to assign a custom domain to your app so you can access it using your own domain.

In this section, we cover how to create, configure and assign a custom domain to your Koyeb app using:

1. The Koyeb control panel
2. The Koyeb CLI

Using the Koyeb control panel

On the Koyeb control panel, go to the Domains configuration page.

In the Add Domain section, enter your custom domain name, select the Koyeb app to assign the domain, and click the Add Domain button.

Your domain appears on the Domains list and indicates the record to create on to your DNS provider to complete your domain configuration.

Once the DNS record is created on your DNS provider, hit the Refresh button. Your domain status changes to Active and you can now access your app using your custom domain.

Using the Koyeb CLI

You can also use the Koyeb CLI to add and assign a custom domain to your Koyeb apps.

For instance to add the custom domain my.domain.tld and assign it to the Koyeb app heroku-app-to-koyeb execute the following command:

koyeb domains create my.domain.tld --app heroku-app-to-koyeb

If you are facing configuration issues when configuring your custom domain, check out our troubleshooting section or contact us using the in-app chat.

Database migration

While offering databases is in our roadmap, we don't recommend our users to run stateful workloads such as databases on Koyeb for now.

If you are looking for an alternative solution to run your Heroku database, we strongly encourage you to check out the following post highlighting awesome database specialized providers offering PostgreSQL, MySQL, MongoDB, Redis, and more.

Conclusion

In this guide, we explained how to migrate a Heroku app from the ground-up on Koyeb using both the Koyeb control panel and CLI.

We covered how to migrate Heroku environment variables to a Koyeb service and assign a custom domain to a Koyeb app.

The application deployed automatically benefits from the Koyeb built-in continuous deployment pipeline. Each change you push to your repository will automatically trigger a new build and deployment on the Koyeb Serverless Platform. Your changes then go live as soon as the deployment passes all necessary health checks. In case of a failure during one of your deployments, we ensure to keep the latest working deployment active so your application is always up and running.

If you would like to read more Koyeb tutorials, checkout out our tutorials collection. Have an idea for a tutorial you'd like us to cover? Let us know by joining the conversation over on the Koyeb community platform!