This guide describes how to migrate your application running on Heroku to AWS with Qovery. It covers all the 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 accounts. 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
orDockerfile
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 (setPrivate
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 😎
loom.com/share/da31c21f9c104eae9270e4c4db59..
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
How to rollback?
Check out the app rollback documentation
How auto-scaling works?
Check out the app auto-scaling documentation
How to manage database migration?
Check out our forum reply
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 questions.