
## 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](/docs/apps/build-from-git) 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](/docs/compare/heroku-vs-koyeb) comparison.

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/dvpN23DBBTY"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
></iframe>

_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](https://www.heroku.com) app deployed and running
- A [Koyeb account](https://app.koyeb.com) to deploy and run your Heroku app on Koyeb
- A [GitHub](https://github.com) repository containing your Heroku code
- The [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) installed on your machine
- The [Koyeb CLI](/docs/cli/installation) 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](#create-a-new-koyeb-app-and-service)
2. [Import your Heroku environment variables](#import-your-heroku-environment-variables)
3. [Configure a custom domain](#configure-a-custom-domain)
4. [Database migration (optional)](#database-migration)

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](#using-the-koyeb-control-panel)
2. [The Koyeb CLI](#using-the-koyeb-cli)

### Using the Koyeb control panel

Go to the **Overview** tab of the [Koyeb control panel](https://app.koyeb.com) 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](/docs/quickstart/koyeb-cli#login) 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:

```bash
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._

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

```bash
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](#using-the-koyeb-control-panel-1)
2. [The Koyeb CLI](#using-the-koyeb-cli-1)

### Using the Koyeb control panel

On the Koyeb control panel, go to the [Domains](https://app.koyeb.com/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:

```bash
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](/docs/quickstart/custom-domains#troubleshooting) section or contact us using the in-app chat.

## Database migration

While offering databases is in our [roadmap](https://feedback.koyeb.com/feature-requests/p/managed-database-offering), 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](/blog/which-cloud-database-platform-to-choose-for-your-applications)
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](https://app.koyeb.com) and [CLI](/docs/quickstart/koyeb-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](/tutorials). 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](https://community.koyeb.com/)**!


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

Migrate from Heroku to Koyeb


## Introduction

Heroku provides managed Postres databases and makes them accessible over the Internet. Whether you are an existing Heroku user wanting to deploy your apps globally while keeping your database on Heroku or looking for a place to host a managed Postgres database, this guide explains how to use and connect a Heroku Postgres database from an application running on Koyeb.

Heroku allows you to create Heroku Apps using add-ons. Since its managed PostgreSQL database is an add-on, this means you can create a Heroku app that only runs the Postgres database without having to deploy your entire application on Heroku.

In this guide, we will create a Heroku App with a Heroku Postgres add-on, create a simple Node.js application to connect the database and deploy the application on Koyeb.

## Requirements

For this guide, you need:

- A [Koyeb account](https://app.koyeb.com/auth/signin) to deploy and run the Node application
- A [Heroku account](https://id.heroku.com/login) to run the Heroku Postgress add-on
- The [Koyeb CLI](https://github.com/koyeb/koyeb-cli) installed to interact with Koyeb from the command line
- A registry that will store our Node app Docker image that will be deployed on Koyeb

## Steps

To use and connect a Heroku Postgres database on Koyeb, you need to follow these steps:

1. [**Create a Heroku App with the Postgres add-on**](#create-a-heroku-app-with-the-postgres-add-on)
2. [**Write a Node.js app connection to the Heroku Postgres database**](#write-a-node-js-app-to-connect-to-the-heroku-postgres-database)
3. [**Deploy the Node.js app on Koyeb**](#deploy-the-node-js-app-on-koyeb)

## Create a Heroku App with the Postgres add-on

In the Heroku [control panel](https://dashboard.heroku.com/), on the top right navigation bar, click the **Create** button and select **Create new app**.
You land on the App creation form where you need to:

- Give your application a name
- Choose the region your App will be located: Europe or the United-States

Once the form is filled in, click the **Create app** button. Then click the **Resources** tab and in the **Add-ons** section of the page fill the search input with **Heroku Postgres** and validate.
A modal opens and asks you to select the plan you want to use. In this guide, we use the Heroku Postgres add-on free tier **Hobby Dev**. Once the plan you want to use is selected, click **Submit order form**.

## Write a Node.js app to connect to the Heroku Postgres database

With the Heroku Postgres add-on deployed, we will now create a basic Node application to connect the database. We will then deploy this application on Koyeb.

### Initialize the environment

```bash
mkdir node-demo
cd node-demo
yarn init
yarn add express sequelize pg pg-hstore
```

### Create the app

In the `node-demo` directory, create a new file `app.js` and paste the snippet below.
The app uses Express and Sequelize to connect the Heroku database and expose an API endpoint on `/` to return Todo mock data from the database.

```js
const { Sequelize } = require('sequelize')
const express = require('express')

const port = 3000(async () => {
  try {
    const sequelize = new Sequelize(process.env.PG_URL, {
      dialectOptions: {
        ssl: { sslmode: 'true', rejectUnauthorized: false },
      },
    })
    await sequelize.authenticate()
    console.log('Connection has been established successfully.')

    console.log('Create fake data.')
    const todos = sequelize.define('todos', { todo: Sequelize.TEXT })
    await sequelize.sync({ force: true })

    await todos.bulkCreate([
      { todo: 'Create a Koyeb account.' },
      { todo: 'Deploy my app.' },
      { todo: 'Enjoy!' },
    ])

    const app = express()

    app.get('/', async (_, res) => {
      items = await todos.findAll()
      res.json(items)
    })
    app.listen(port, () => {
      console.log(`Demo app listening at http://localhost:${port}`)
    })
  } catch (error) {
    console.error('Unable to connect to the database:', error)
  }
})()
```

### Write the Dockerfile and build the Docker image

To Dockerize our Node.js app, you need to create a `Dockerfile` in your project folder containing the content below.

```dockerfile
FROM node:lts as runner
WORKDIR /node-express
ENV NODE_ENV production
COPY . .
RUN npm ci --only=production
EXPOSE 3000
CMD ["node", "app.js"]
```

To build and properly tag the Docker image execute the following command:

```bash
docker build . -t ghcr.io/<YOUR_GITHUB_USERNAME>/node-app
```

_In this guide, we will push the Docker image to a GitHub container registry. You are free to use another different registry as Koyeb allows you to deploy from any container registry._

Once the build is over, you can run a container using the image locally to validate everything is working as expected running:

```bash
docker run -p 3000:3000 ghcr.io/<YOUR_GITHUB_USERNAME>/node-app
```

As in the previous step, you can perform a curl request to ensure the app is running as expected:

```bash
$curl http://localhost:3000/
[
  {
    "id": 1,
    "todo": "Create a Koyeb account.",
    "createdAt": "2021-07-21T10:18:16.576Z",
    "updatedAt": "2021-07-21T10:18:16.576Z"
  },
  {
    "id": 2,
    "todo": "Deploy my app.",
    "createdAt": "2021-07-21T10:18:16.576Z",
    "updatedAt": "2021-07-21T10:18:16.576Z"
  },
  {
    "id": 3,
    "todo": "Enjoy!",
    "createdAt": "2021-07-21T10:18:16.576Z",
    "updatedAt": "2021-07-21T10:18:16.576Z"
  }
]
```

### Push the Docker image to the GitHub container registry

With the Docker image built and functional, we can now upload it to the GitHub container registry.
In your terminal run the command below to push the image:

```bash
ghcr.io/<YOUR_GITHUB_USERNAME>/node-app
```

Once the push command is completed, the Docker image is stored in your GitHub container registry.

## Deploy the Node.js app on Koyeb

We are now ready to deploy our application on Koyeb. First, create a Koyeb Secret to store your container registry configuration.
In this guide, we will deploy our app from the GitHub container registry. For other container registries examples, check out this related [documentation](/docs/apps/private-container-registry-secrets).

_If your Docker image is public, there is no need to create a secret containing your container registry configuration._

```bash
echo \
'{
  "auths": {
    "https://ghcr.io": {
      "username": "<REPLACE_ME_WITH_GITHUB_USERNAME>",
      "password": "<REPLACE_ME_WITH_GITHUB_TOKEN>"
    }
  }
}' | koyeb secrets create ghcr-credentials
```

Then, create a second secret to securely store your Heroku Postgres database connection string.
You can retrieve the information from the [Heroku control panel](https://data.heroku.com/), selecting your database, clicking the **Settings** tab and clicking the **View credentials** button.

Copy the URI and create the Koyeb secret to securely store running in your terminal:

```bash
$koyeb secrets create heroku-pg-url
postgres://...
```

We are now ready to deploy our application, in the terminal run:

```bash
koyeb app init node-app --docker "ghcr.io/<YOUR_GITHUB_USERNAME>/node-app" --ports 3000:http --routes /:3000 --docker-private-registry-secret ghcr-credentials --env PG_URL=@heroku-pg-url
```

This command creates a new Koyeb App and deploys our Node application exposing port 3000 and making it publicly accessible on the `/` route of your Koyeb App URL.

To retrieve your Koyeb App URL and access your application, run:

```bash
$koyeb app get node-app
ID                                  	NAME           	DOMAINS                             	UPDATED AT
d58ebed1-48c0-46b7-a2f1-91f3ffdbccf2	node-app        node-app-<YOUR_ORG>.koyeb.app         2021-06-23 09:46:55.411403 +0000 UTC
```

Open the URL in your browser to access your application running on Koyeb. The application returns the mock Todo data stored in the Heroku Postgres database.
By running your application on Koyeb you benefit from native autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network allowing you to make your applications faster and distribute your content near your users thanks to Koyeb's 55 edge locations.


This guide explains how to use and connect an Heroku Postgres database from a Koyeb app.

Heroku

Migrate from Heroku to Koyeb

How to use Heroku Postgres with Koyeb Serverless Platform