As a programmer developing a Strapi API, you will have, sooner or later, to deploy your app online. To do so, many options are available.

The default one is to use a Linux instance on a IaaS (Infrastructure as a Service) provider such as AWS or DigitalOcean, and configure it for your app. However, this option is complex and may involve some critical security issues if you are not familiar with DevOps.

In order to make hosting easier, a new kind of solution emerged in the last few years: Platforms as a Service (PaaS). The idea behind this concept is to make hosting way easier and let developers focus on their code instead of their servers infrastructure. The most famous one is definitely Heroku. Heroku relies on AWS and is trusted by thousands of companies.

Many of you wanted to discover how to easily deploy a Strapi app on Heroku. It didn't fall on deaf ears. This tutorial intends to explain you the necessary steps to push in production a clean Strapi app, using Heroku for both hosting and database.

First of all, we are going to configure a Heroku account. Then, we will generate a brand new Strapi API and deploy it. As a bonus, you will also discover the one-click deploy button:

Heroku setup

Heroku is an online service, so, except if you already have an account (go to section "Heroku CLI setup"), you need to create one:

Register

Visit the register page, fill in the form and submit it:

Validate your email address

To complete the registration process, validate your email address by clicking on the link in the email you received from Heroku and choose a password:

That's it, your account is up and running:

Let's go further!

Heroku CLI setup

Heroku offers a powerful CLI to manage your apps through your terminal.

Installation

To install the CLI, follow the instructions corresponding to your operating system:

Debian/Ubuntu

$ wget -qO- https://cli-assets.heroku.com/install-ubuntu.sh | sh

MacOS

$ brew install heroku/brew/heroku

Make sure Homebrew is installed on your computer.

Windows

Download and run the Windows installer 32-bit 64-bit.

Note: if you encounter any issue, take a look at the Heroku CLI documentation.

Login

In order to link your Heroku account, you need to login:

$ heroku login

Congrats, you successfully created a Heroku account and configured the Heroku the CLI!

Install Strapi

Requirements: please make sure Node 9 is installed on your machine.

Install Strapi using npm:

$ npm i strapi@alpha -g

Generate a new Strapi project

To create a new project, simply run the following command:

$ strapi new my-app

Press enter to use the default answers for each question.

⚠️ UPDATE: in latest version of Strapi you will have to set the config value: Authentication database the value has to be the database name

Init the git repository

Git is the de-facto solution to version code. Heroku highly relies on it to detect changes. That means everytime you update your codebase, you only need to commit your changes and push them to Heroku.

Our app is not versioned yet, so we are going to init the Git repository, add the files and submit the first commit:

$ cd my-app
$ git init
$ git add .
$ git commit -am "Initial commit"

Heroku create

We have never been so closed to the deployment. Let's inform Heroku we want to create a new project:

$ heroku create

At this point, you should already be able to see the app in your Heroku dashboard:

mLab addon

By default, a Strapi API needs a MongoDB database. Locally, you can use a MongoDB instance running on your machine. Especially when it comes to deployment, you need to install MongoDB on a remote server or use a Database as a Service provider, such as mLab.

To make things even more easier, Heroku created the addons system. Addons are integrated tools and services for developing, extending, and operating apps. All kind of addons are available: Monitoring, Email/SMS, Testing, Search, Image Processing, etc. and, obviously, Data Stores. MongoDB is provided in Heroku addons through several services, including Compose, ObjectRocket and mLab.

In this tutorial, we are going to use the mLab addon, which provides a free Sandbox plan. If you plan to deploy your app in production, we highly recommend you to switch to a paid plan.

mLab addon exposes an environment variable named MONGODB_URI to your project. Its value is a string looking like this: mongodb://heroku_12345678:random_password@ds029017.mLab.com:29017/heroku_12345678. As you can see, it contains all the necessary informations to connect to the MongoDB instance: username, password, host, port and database name. Give a look at the documentation for more details.

To make sure our deployment will be successful, we must make sure that the environment variable will be handled by the Strapi app. Don't worry, we have prepared everything for you in Strapi (from v3@alpha.9.3). As you can see in config/environments/production/database.json, Strapi uses by default some environment variable:

{
  "defaultConnection": "default",
  "connections": {
    "default": {
      "connector": "strapi-mongoose",
      "settings": {
        "client": "mongo",
        "uri": "${process.env.DATABASE_URI || ''}",
        "host": "${process.env.DATABASE_HOST || 'localhost'}",
        "port": "${process.env.DATABASE_PORT || 27017}",
        "database": "${process.env.DATABASE_NAME || 'production'}",
        "username": "${process.env.DATABASE_USERNAME || ''}",
        "password": "${process.env.DATABASE_PASSWORD || ''}"
      },
      "options": {
        "authenticationDatabase": "${process.env.DATABASE_NAME || 'production'}",
        "ssl": false
      }
    }
  }
}

That means Strapi automatically use the environment variables available. But, the variable specified in Strapi is DATABASE_URI, not MONGODB_URI. Why? Because we want to keep Strapi generic, not specific to some hosting platforms. Fortunately, Heroku allows us to rename the exposed variable thanks to the alias system. This is why we specify -as DATABASE when creating the addon.

Now that you know a bit more about addons, let's create one:

$ heroku addons:create mongolab:sandbox --as DATABASE

Note: if you want to deploy a project using Strapi < v3@alpha.9.3, please copy and paste the JSON content above in config/environments/production/database.json and replace the line 3 in config/environments/production/server.json by "port": "${process.env.PORT || 1337}".

Deploy to Heroku

Let's make the magic happen! Push your code to Heroku:

$ git push heroku master

This is as simple as that! Click on the link at the bottom of the logs to discover your Strapi app online:

Bonus - Introducing the one-click deploy

Because deployment is never too easy, Heroku introduced the deploy button. This button allows open-source projects owners (and others) to let users deploy apps within one click.

Since it can be a huge benefit for current and future Strapi users to preview what Strapi is, we decided to make it available for you.

From now, you can deploy a Strapi app just by clicking on this button:

After that, to do any update, clone it using the Heroku git URL (heroku info heroku-project-name) and customize it according to your needs.

An example is available at the following address: https://strapi-heroku-app.herokuapp.com (username: demo@strapi.io / password: demo).

Conclusion

Congratulations! You successfully deployed a brand new Strapi app on Heroku.

In this tutorial, we have seen various aspects of Heroku concepts. To go deeper and perfectly setup your app for production, we strongly recommend you to read the documentation about topics such as scalability, GitHub based deployments, pipelines, etc.

We hope you enjoyed this tutorial. Please comment it to give your feedback and explain how you usually deploy your Strapi APIs.