Deploying a Strapi API on Heroku in 5 min

This article refers to Strapi v4. For Strapi v5, use the resources below:

Start here

• Strapi 5 docs (source of truth): Strapi 5 Documentation — official hub for setup, modeling, APIs, and deployment.

Local setup & project creation

• Installation prerequisites (Node v20/v22): Install requirements — confirm supported Node versions before you start.
• Create a new app (CLI): Installing from CLI — bootstrap a v5 project and learn the develop/start commands.

Use PostgreSQL on Heroku (not SQLite)

• Database configuration (Postgres): Database configuration — define a production connection using Postgres.
• Environment variables & secrets: Environment configuration — set APP_KEYS, ADMIN_JWT_SECRET, JWT_SECRET, etc., via env vars.

File uploads on PaaS

• Heroku tip — ephemeral filesystem: FAQ — dynos reset; use an external upload provider instead of local disk.
• Upload/Media providers: Media Library — overview and links to configure providers.

Deploy & production behavior

• Deployment overview: Deployment — prepare builds and run Strapi in production.
• CT Builder is dev‑only: Content‑Type Builder — disabled under strapi start in production; design content-types in development.

Move data local ↔ Heroku

• Data Transfer CLI: Data transfer — use strapi transfer to move content, files, and config between instances.

Optional (if your app uses GraphQL)

• GraphQL plugin: GraphQL plugin — install and enable /graphql for queries/mutations.

Still on v4?

• Upgrade v4 → v5 (step‑by‑step): Migration guide — migrate first, then deploy.
• Breaking changes index: Breaking changes — what changed between v4 and v5.

Strapi is one of the best CMS’s out there. There are many options for deploying to choose from such AWS or DigitalOcean, Azure, Google App Engine or render. However, these are not that trivial for someone who is not experienced in DevOps. I will walk you through how to install your Strapi instance in Heroku.

What is Heroku?

Heroku is a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud. It supports several languages such as Java, Nodejs, Go, PHP, Python. Strapi is a Nodejs application!

What We Need

To get started, we will need to have the following in place:

• Github Account
• Heroku Account
• Git Installed on your machine
• Nodejs v16+ installed
• Code Editor (I use VScode)

Goal

At the end of this guide, you should be able to:

• Install Strapi Locally
• Push your Strapi codebase to Github
• Connect your Heroku account to your Github(the project repository) and enable Automatic Deploy
• Connect your Strapi project to Postgres add-on database provided by Heroku.

Installing Strapi Locally

To install Strapi, run this on your machine:

    npx create-strapi-app my-project --quickstart

This will create a folder called my-project and automatically install Strapi. After that, you should be able to access http://localhost:1337/admin . Opening this for the first time will redirect you to http://localhost:1337/admin/auth/register-admin . This is because we have no super admin yet in the database. By default, Strapi uses SQLite as a file-based database.

You need to create your first super admin locally. I want you to know that Heroku does not completely support SQLite. Read more about SQLite support. So it is important to understand that the super admin you will be creating locally will differ from the one that you will create when you host on Heroku. And of course, you need to have a super admin locally because that is how you will be able to create a new collection type schema as Strapi does not allow that to be done in production.

Create a Repository and Pushing to Github

Heroku has a Command Line Interface (CLI) that can be used to push your code directly to its platform. However, using GitHub to version control your codebase is more organised.

So you need to create a git repository on GitHub and run the following command in the root of your Strapi instance.

1    git init
2    git add .
3    git commit -m "first commit"
4    git branch -M main
5    git remote add origin https://github.com/USERNAME/NAMEOFREPOSITORY.git
6    git push -u origin main

Where USERNAME is your GitHub username and NAMEOFREPOSITORY is the name given to your just created repository.

Connecting to Heroku

For Heroku to have access to your GitHub code, it is important that you log in to your GitHub account in the same browser that your Heroku account is logged in.

Your Heroku dashboard should look like so if you do not have an existing application:

Click on Create new app.

Input your app name (Heroku will tell you if the name is available).

Then click on Create app.

Choose GitHub as the Deployment Method

Then search the repository you wanted to deploy.

Enable Automatic Deploys:

What this does is that whenever you push new changes from the local laptop to your GitHub, these changes will be deployed automatically on Heroku.

Then Deploy.

This is going to take a while to deploy and build(usually less than 2 minutes). Afterward, you can view you application by clicking View

You have successfully deployed your Strapi application on Heroku. That is not all. Remember what I said about SQLite database not being supported by Heroku. Creating a new super admin in the Heroku instance with connecting to another database will always wipe off your data every 24 hours and this is not good. To fix this, we are going to be using the PostgreSQL Database provided by Heroku add-on (you can use any services you which).

Using Heroku Postgres Addon as Database

The default Sqlite database Strapi ships with is not production-ready, If you are deploying to Heroku, chances are that you would not want you data to keeps deleting every time your dyno sleeps, So we will be using Postgres database that is provided by Heroku.

To do that, on your app created on Heroku, go to the Resources tab. Search for Heroku Postgres on the Add-ons sections.

Click on Heroku Postgres, you should get this:

Click on Submit Order Form

Now, go to the Settings tab.

Clicking Reveal Config Vars will only display DATABASE_URL with its long value. This is how the full syntax should look like:

postgres://{user}:{password}@{hostname}:{port}/{database-name}

While checking your config variables in your Heroku dashboard, as per the Strapi documentation, you will have add a few environment variables as follows.

• APP_KEYS: In your terminal run openssl rand -base64 32
• API_TOKEN_SALT: In your terminal run openssl rand -base64 32
• ADMIN_JWT_SECRET: In your terminal run openssl rand -base64 32
• JWT_SECRET: In your terminal run openssl rand -base64 32

Adding Environment Variables to Strapi

Your default local development database configuration can be found in your Strapi project at ./config/database.js

In your config folder, create a folder called env and in that folder create a folder called production. In your production folder, create a file called database.js and the following code inside it. Your file URL should look like this env/production/database.js

1    const parse = require('pg-connection-string').parse;
2    const config = parse(process.env.DATABASE_URL);
3    module.exports = ({ env }) => ({
4      connection: {
5        client: 'postgres',
6        connection: {
7          host: config.host,
8          port: config.port,
9          database: config.database,
10          user: config.user,
11          password: config.password,
12          ssl: {
13            rejectUnauthorized: false
14          },
15        },
16        debug: false,
17      },
18    });

Notice that we are using a pg-connection package here. This contains functions for dealing with a PostgresSQL connection string. This is because we do not want to assign too many environment variables. We need to install this package.

Run this:

    yarn add pg-connection-string 

and also install Postgres client as well:

1    yarn add pg

It is important that you use yarn to install the above packages instead of npm else it will fail during build time.

Now, add, commit, and push your code to Github, and since your Heroku app is linked to the repository, it will take less than 2 minutes to build and everything should start working. if you add /admin to the hosted Strapi URL, it will prompt you to add a super admin, but this time, it will be saved in the Postgres database and will not delete when the dyno sleeps(If you are on the free dyno type)

Conclusion

Congratulations, you have seen it to the end of this guide. You have seen how to install Strapi locally and deploy on Heroku, we even went ahead to use an add-on Postgres database provided by Heroku.