The ultimate guide to migrate from Heroku to AWS in 1 hour
Tags: aws, heroku
Published: 2022-05-21 12:41:27

This guide describes how to migrate your application running on Heroku to AWS with [Qovery](https://www.qovery.com). It covers all required steps you need to take to deploy your application on AWS and transfer your data from Heroku Postgres to the database managed by AWS.

> _Qovery is a platform used by more than 22 000 developers to deploy their apps on their AWS account. It's the "Heroku-like" experience on top of AWS._

This is the final result 😎

<a href="https://www.loom.com/share/da31c21f9c104eae9270e4c4db59055e">
    <img src="https://cdn.loom.com/sessions/thumbnails/da31c21f9c104eae9270e4c4db59055e-with-play.gif">
</a>

## Assumptions 👨‍🏫

* You have an application on Heroku
* You are familiar with Heroku basics, have a Heroku account and access to Heroku CLI
* You have [sign in on Qovery](https://start.qovery.com)
* You have [set up your AWS account](https://hub.qovery.com/guides/tutorial/how-to-deploy-your-application-on-aws-in-30-minutes/) with Qovery

## Costs 💵

* Qovery installs an EC2 instance (perfect for hobby project) or an EKS cluster (perfect for production) on your AWS account.
* Qovery is free up to 100 deployments/month (see [pricing](https://www.qovery.com/pricing))

## Migration Steps 🪜

1. Use Buildpacks or Create your Dockerfile
2. Create resources on Qovery
3. Configure Environment Variables and Secrets
4. Copy data from your Heroku databases to your AWS databases
5. Deploy your apps
6. FAQ by Heroku users

## 1. Create your Dockerfile or Use Buildpacks 🍃

Qovery supports two ways to build and run your application coming from Heroku:

1. Buildpacks
2. Docker

Both options build a container image that is runnable by a container engine (E.g. Docker). Qovery runs containers on Kubernetes.

> I will explain how to use Buildpacks. Refer to [the original guide](https://hub.qovery.com/guides/tutorial/migrate-your-application-from-heroku-to-aws/#1-create-your-dockerfile-or-use-buildpacks) to get instructions to use a Dockerfile.

[Buildpacks](https://buildpacks.io/) automatically detects the language and the framework your application is using. Buildpacks builds and runs your app. Here is the list of [supported languages and frameworks](https://hub.qovery.com/docs/using-qovery/configuration/application/#option-1-buildpacks).

**Supported languages**

| language   | version |
|------------|---------|
| Node.JS    | any     |
| Clojure    | any     |
| Python     | any     |
| Java       | any     |
| Gradle     | any     |
| JVM        | any     |
| Grails     | any     |
| Scala      | any     |
| Play       | any     |
| PHP        | any     |
| Go         | any     |

----

⚠️ We do recommend using Docker to keep the full control of what's going on behind the scene. Buildpacks is a great technology but difficult to debug when something goes wrong. You can try deploying your apps on AWS with Qovery with Buildpacks, if you do not succeed, we do recommend switching for Docker.

----

### Limitations 👀

Here are some limitations due to our Buildpacks implementation:

* Qovery Buildpacks does not support Procfile with multiple commands at the moment.
* Qovery does not support custom Buildpacks.

Those limitations will be solved in the coming months.

## 2. Create resources on Qovery 👩‍💻

### Application

<a href="https://www.loom.com/share/9246ae68c68f42debc3d5183d2b4f7f8">
    <img src="https://cdn.loom.com/sessions/thumbnails/9246ae68c68f42debc3d5183d2b4f7f8-with-play.gif">
</a>

Steps:

1. Connect to the [Qovery console](https://start.qovery.com).
2. Create your [Organization](https://hub.qovery.com/docs/using-qovery/configuration/organization/) and your [Project](https://hub.qovery.com/docs/using-qovery/configuration/project/).
3. Create an environment with the name `production` (it can be changed after).
4. Create an application and give it a name (you can give the name of your repo if you have no idea)
5. Select your app repository from your GitHub, GitLab or Bitbucket.
6. Select the branch you want to deploy.
7. Select the Build mode for `Buildpacks` or `Dockerfile` according to what you want.
8. Specify the local listening port of your application.
9. Click on "create"

Congrats! Your application is created 🎉

----

⚠️ Your application is created but not deployed yet! You can configure the vCPU, Memory, Environment Variables... before deploying it. If you want to deploy it before finishing the configuration you can click on "Actions" > "Deploy".

----

If you deploy an app from a mono-repository, we have a must-read guide for you [here](https://hub.qovery.com/guides/advanced/monorepository/).

### Database ⚡️

Here are the steps to deploy your database:

<a href="https://www.loom.com/share/d7e10be0e5964f6799b158dc631bbbd1">
    <img src="https://cdn.loom.com/sessions/thumbnails/d7e10be0e5964f6799b158dc631bbbd1-with-play.gif">
</a>

Steps:

1. Go to your `production` environment.
2. Add your database by clicking on "Add" > "Database".
3. Select the database (PostgreSQL, MySQL, MongoDB, Redis..) and the version you want to deploy.
4. Select [Managed or Container mode](https://hub.qovery.com/docs/using-qovery/configuration/database/#modes) for your database.
5. Select `Public` accessibility (set `Private` if you don't want to restore your data from an existing Heroku database).

Congrats! Your database is created as well 🎉

If you use MongoDB Atlas, or an existing database on AWS that you want to connect to your application deployed by Qovery. Check out [our tutorial about VPC peering](https://hub.qovery.com/guides/tutorial/aws-vpc-peering-with-qovery/) and how to securely connect to your existing database.

## 3. Configure your Environment Variables and Secrets 🛡

Qovery makes the difference between an [Environment Variable](https://hub.qovery.com/docs/using-qovery/configuration/environment-variable) and a [Secret](https://hub.qovery.com/docs/using-qovery/configuration/secret/). Basically, a Secret is similar to an Environment Variable but the value is encrypted and can't be revealed. Both are injected as environment variables during the build and the run of your applications.

To extract your environment variables from Heroku, we recommend using the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and exporting all the environment variables and secrets in an .env (dot env) file. Qovery supports the [import of a dot env file](https://hub.qovery.com/guides/tutorial/import-your-environment-variables-with-the-qovery-cli/) via the Qovery web interface and the Qovery CLI.

----

⚠️ If you use Buildpacks for one of your app AND you have indicated a local listening port of your application, you will need to add an environment variable `PORT` with the value of your port to make your application starting properly. Otherwise, Qovery will fail to deploy your app!

----

[Export your environment variable via the Heroku CLI](https://devcenter.heroku.com/articles/config-vars#view-current-config-var-values) with the command:

```shell
# To install Heroku CLI: https://devcenter.heroku.com/articles/heroku-cli
heroku config

GREETINGS: hello world
STRIPE_API_KEY: xxx-yyy-zzz
IS_PRODUCTION: true
```

Then you can create your environment variables via the web interface (watch the video below)

<a href="https://www.loom.com/share/50899d7fa3d84a418f0db69f54f970d3">
    <img src="https://cdn.loom.com/sessions/thumbnails/50899d7fa3d84a418f0db69f54f970d3-with-play.gif">
</a>

Or via the [Qovery CLI](https://hub.qovery.com/docs/using-qovery/interface/cli/):

```shell
# auth yourself
qovery auth

# selection the app where you want to import your environment variables
qovery context set

# import your Heroku environment variables
heroku config --app <your_heroku_app_name> --json | qovery env import --heroku-json

Qovery: Heroku environment variables import from JSON
? Do you want to import Environment Variables or Secrets? Environment Variables
? What environment variables do you want to import?  [Use arrows to move, space to select, <right> to all, <left> to none, type to filter]
  [x]  GREETINGS=hello world
  [ ]  STRIPE_API_KEY=xxx-yyy-zzz
> [x]  IS_PRODUCTION=true

Qovery: ✅ Environment Variables successfully imported!
```

----

⚠️ Import sensitive data (E.g. API keys, credentials...) as `Secret` and not `Environment Variable`.

----

### Connect your frontend app to your backend app

To connect your frontend app your backend app we will create an [environment variable alias][docs.using-qovery.configuration.environment-variable#alias-environment-variable].

Here is how to create a frontend app:

<a href="https://www.loom.com/share/bafbbda93bd64d04afb3189bf4a1a201">
    <img src="https://cdn.loom.com/sessions/thumbnails/bafbbda93bd64d04afb3189bf4a1a201-with-play.gif">
</a>

And now how to connect your frontend app with your backend app:

<a href="https://www.loom.com/share/f820925f2175465f9271b97ef414bb42">
    <img src="https://cdn.loom.com/sessions/thumbnails/f820925f2175465f9271b97ef414bb42-with-play.gif">
</a>

You can also take a look at [this forum reply](https://discuss.qovery.com/t/918) to learn how to do it.


### Connect your backend app to your database

Same as connecting your frontend app to your backend app, you can create an environment variable alias `DATABASE_URL` for the *built-in* secret finishing with `_DATABASE_URL_INTERNAL`.

----

⚠️ Create an alias on `_DATABASE_URL_INTERNAL` and not `_DATABASE_URL`

----

<a href="https://www.loom.com/share/59f8368eb3c14796a807c7e39e9c0ab0">
    <img src="https://cdn.loom.com/sessions/thumbnails/59f8368eb3c14796a807c7e39e9c0ab0-with-play.gif">
</a>

## 4. Copy data from your Heroku databases to your AWS databases

*Coming soon with [Replibyte](https://www.replibyte.com)*

## 5. Deploy your apps!

We are finally ready to deploy my applications on AWS!

<a href="https://www.loom.com/share/0589d2f2aa4149edb605dc23f4efd23d">
    <img src="https://cdn.loom.com/sessions/thumbnails/0589d2f2aa4149edb605dc23f4efd23d-with-play.gif">
</a>

Watch the final result 😎

https://www.loom.com/share/da31c21f9c104eae9270e4c4db59055e

## FAQ by Heroku users

### How to create a custom domain?

Check out the documentation on [how to configure your custom domain](https://hub.qovery.com/guides/getting-started/setting-custom-domain/).

### How to monitor my apps?

We do recommend using [Datadog](https://www.datadoghq.com) or any other monitoring products for monitoring your apps deployed by Qovery. Check out [our tutorial on how to install Datadog](https://hub.qovery.com/guides/tutorial/kubernetes-observability-and-monitoring-with-datadog/)

### Do you have Heroku "Review App" equivalent?

Yes, it's what we call [Preview Environment](https://hub.qovery.com/docs/using-qovery/configuration/environment/#preview-environment)

### How to rollback?

Check out the [app rollback documentation](https://hub.qovery.com/docs/using-qovery/configuration/application/#update-and-rollback)

### How auto-scaling works?

Check out the [app auto-scaling documentation](https://hub.qovery.com/docs/using-qovery/configuration/application/#auto-scaling)

### How to manage database migration?

Check out [our forum reply](https://discuss.qovery.com/t/951)

### Is it possible to get a shell / connect to my app?

Yes, with the Qovery CLI and the command `qovery shell`. [Check out the documentation](https://hub.qovery.com/docs/using-qovery/interface/cli/#shell).

### Can I use Terraform and Infrastructure as Code?

Absolutely, we have a [Qovery Terraform provider](https://hub.qovery.com/docs/devops/infrastructure-as-code/terraform/) available.

### How can I connect my app to MongoDB Atlas?

If you use MongoDB Atlas check out [our tutorial about VPC peering](https://hub.qovery.com/guides/tutorial/aws-vpc-peering-with-qovery/) and how to securely connect to your existing MongoDB Atlas database.

### How can I connect my app to an AWS service not managed by Qovery?

If you want to connect your app to an AWS service not managed by Qovery, check out [our tutorial about VPC peering](https://hub.qovery.com/guides/tutorial/aws-vpc-peering-with-qovery/) and how to securely connect to this AWS service.

----

If you have a common question about Qovery, we have a more general [FAQ section](https://hub.qovery.com/docs/useful-resources/faq/) available.

## Wrapping up 👋🏼

Congrats! You have migrated from Heroku to AWS. Feel free to check out our [forum](https://discuss.qovery.com) and open a thread if you have any question.