# Deploy to Heroku

The purpose of this guide is to allow users to deploy Strapi applications on Heroku. This guide uses the Heroku CLI tool with a PostgreSQL database provided by Heroku. There are other options for how to deploy to Heroku available in the Heroku documentation (opens new window).

✋ CAUTION

Prior to starting the deployment process, each user needs:

# Setup a Strapi project for deployment

Strapi uses environment configurations to maintain multiple environments inside a single application. This section describes how to set up a production environment in a Strapi application.

  1. Add a production configuration environment by creating a sub-directory ./config/env/production.
  2. Create database.js inside the ./config/env/production directory.
  3. Add the following code snippet to the database configuration file:
  1. Create server.js inside the ./config/env/production directory.
  2. Add the following code snippet to the server configuration file:

  1. Add PostgreSQL dependencies by installing pg package (opens new window) and pg-connection-string package (opens new window):

  2. Add package-lock.json to the end of the .gitignore file at the root of the Strapi project:

    # path: ./.gitignore
package-lock.json
    1
    2

    ✏️ NOTE

    It is usually recommended to version the package-lock.json file, but it is known to cause issues on Heroku.

  3. Verify that all of the new and modified files are saved locally.

  4. Commit the project to a local repository:

    git init
git add .
git commit -m "commit message"
    1
    2
    3

# Create and configure a Heroku App

Deploying to Heroku requires installing the CLI tool, creating an App, connecting the App to a database, and setting environment variables. At the end of the following steps, a Strapi application should be successfully deployed.

# Install and use the Heroku CLI

  1. Use the following OS-specific installation instructions to install the Heroku CLI tool:

  2. Login to Heroku from the CLI, following the command-line instructions:

    heroku login
    1

# Create a Heroku project

Create a new Heroku project by running the following command in the root directory of the Strapi project:

# path: ./my-project/
heroku create
1
2

💡 TIP

The command heroku create custom-project-name, creates the custom-project-name.heroku.com URL. Otherwise, Heroku automatically generates a random project name (and URL).

To initialize a local project folder with an existing Heroku project use the following command:

# path: ./my-project/
heroku git:remote -a your-heroku-app-name
1
2

The local development environment is now set up and configured to work with Heroku.

# Create a Heroku database

The following command creates and connects a PostgreSQL database with the Heroku project. Consult the Heroku documentation (opens new window) for database plan names and costs.

#Path: ./my-project/
heroku addons:create heroku-postgresql:<PLAN_NAME>
1
2

The database credentials are stored as a string with the config variable name DATABASE_URL. The database credentials can be retrieved using the following command in the terminal:

# path: ./my-project/
heroku config
1
2

The command output has the form DATABASE_URL: postgres://ebitxebvixeeqd:dc59b16dedb3a1eef84d4999sb4baf@ec2-50-37-231-192.compute-2.amazonaws.com: 5432/d516fp1u21ph7b. The string has the structure postgres://USERNAME:PASSWORD@HOST:PORT/DATABASE_NAME

# Populate the environment variables

Strapi requires the following environment variables to be set for the remote instance:

  • NODE_ENV,
  • MY_HEROKU_URL,
  • JWT_SECRET,
  • ADMIN_JWT_SECRET,
  • API_TOKEN_SALT,
  • APP_KEYS.

The following tabs detail how to either set new values for the secrets or transfer the values from the local .env file. Creating new values is the best practice.

💡 TIP

On Windows, secrets can be generated manually by running node -p "require('crypto').randomBytes(48).toString('base64');" and subsequently set on Heroku using the command heroku config:set SECRET_NAME=your-key-here for each variable.

# Deploy an application to Heroku

In the project root directory run the git push heroku HEAD:main CLI command to push the project to the Heroku server:

# path: ./my-project/`
git push heroku HEAD:main
1
2

The deployment may take a few minutes. At the end, logs will display the URL of the project (e.g. https://mighty-taiga-80884.herokuapp.com). The project can also be opened from the command line:

# path: ./my-project/`
heroku open
1
2

The Strapi Welcome page indicates that the project is correctly set up, configured, and deployed on Heroku. Next, set up an admin user as the production database is brand-new and empty. Add /admin to the end of the website address to access the signup page.

# Project updates

Modifications that require writing to model creation or other JSON files, such as creating or changing content types, require making those changes on the local development environment and then pushing the changes to Heroku. See the documentation FAQ for PaaS and the FAQ for content-types in production for more information.

Further development can benefit from version control (opens new window), or continue using git push heroku HEAD:main to commit and push changes to Heroku directly.

Path: ./my-project/

git add .
git commit -am "Changes to my-project noted"
git push heroku HEAD:main
heroku open
1
2
3
4

💡 TIP

If you encounter the error 'heroku' does not appear to be a git repository when running git push, run the following command: heroku git:remote -a your-app-name.

# File Uploads

Like with project updates on Heroku, the file system doesn't support local uploading of files as they are deleted when Heroku "cycles" the dyno. This type of file system is called ephemeral (opens new window), which means the file system only lasts until the dyno is restarted (with Heroku this happens any time the application is redeployed or during the regular restart which can happen every few hours or every day).

Due to Heroku's filesystem, an upload provider such as AWS S3 or Cloudinary is required. Additional details are available in the installing providers documentation. The Strapi Market contains providers from both Strapi and the community. Additional community providers are available from npmjs.com (opens new window).

← Caddy →