Romaric P.

Posted on May 21, 2022 • Originally published at hub.qovery.com

The ultimate guide to migrate from Heroku to AWS in 1 hour

#aws #heroku

This guide describes how to migrate your application running on Heroku to AWS with Qovery. 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 😎

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
You have set up your AWS account 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)

Migration Steps 🪜

Use Buildpacks or Create your Dockerfile
Create resources on Qovery
Configure Environment Variables and Secrets
Copy data from your Heroku databases to your AWS databases
Deploy your apps
FAQ by Heroku users

1. Create your Dockerfile or Use Buildpacks 🍃

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

Buildpacks
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 to get instructions to use a Dockerfile.

Buildpacks 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.

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

Steps:

Connect to the Qovery console.
Create your Organization and your Project.
Create an environment with the name production (it can be changed after).
Create an application and give it a name (you can give the name of your repo if you have no idea)
Select your app repository from your GitHub, GitLab or Bitbucket.
Select the branch you want to deploy.
Select the Build mode for Buildpacks or Dockerfile according to what you want.
Specify the local listening port of your application.
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.

Database ⚡️

Here are the steps to deploy your database:

Steps:

Go to your production environment.
Add your database by clicking on "Add" > "Database".
Select the database (PostgreSQL, MySQL, MongoDB, Redis..) and the version you want to deploy.
Select Managed or Container mode for your database.
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 and how to securely connect to your existing database.

3. Configure your Environment Variables and Secrets 🛡

Qovery makes the difference between an Environment Variable and a 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 and exporting all the environment variables and secrets in an .env (dot env) file. Qovery supports the import of a dot env file 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 with the command:

# 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)

Or via the Qovery CLI:

# 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:

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

You can also take a look at this forum reply 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

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

Coming soon with Replibyte

5. Deploy your apps!

We are finally ready to deploy my applications on AWS!

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.

How to monitor my apps?

We do recommend using Datadog or any other monitoring products for monitoring your apps deployed by Qovery. Check out our tutorial on how to install Datadog

Do you have Heroku "Review App" equivalent?

Yes, it's what we call Preview Environment

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.

Can I use Terraform and Infrastructure as Code?

Absolutely, we have a Qovery Terraform provider available.

How can I connect my app to MongoDB Atlas?

If you use MongoDB Atlas check out our tutorial about VPC peering 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 and how to securely connect to this AWS service.

If you have a common question about Qovery, we have a more general FAQ section available.

Wrapping up 👋🏼

Congrats! You have migrated from Heroku to AWS. Feel free to check out our forum and open a thread if you have any question.

DEV Community