These integration guides are not official documentation and the Strapi Support Team will not provide assistance with them.
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.
Prior to starting the deployment process, each user needs:
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.
./config/env/production
.database.js
inside the ./config/env/production
directory.Add the following code snippet to the database
configuration file:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// path: ./config/env/production/database.ts
import { parse } from 'pg-connection-string';
const config = parse(process.env.DATABASE_URL);
export default ({ env }) => ({
connection: {
client: 'postgres',
connection: {
host: config.host,
port: config.port,
database: config.database,
user: config.user,
password: config.password,
ssl: {
rejectUnauthorized: false
},
},
debug: false,
},
});
Create server.js
inside the ./config/env/production
directory.
Add the following code snippet to the server
configuration file:
1
2
3
4
5
6
7
8
// Path: ./config/env/production/server.js`
export default ({ env }) => ({
proxy: true,
url: env('MY_HEROKU_URL'), // Sets the public URL of the application.
app: {
keys: env.array('APP_KEYS')
},
});
Add PostgreSQL dependencies by installing pg
package and pg-connection-string
package:
With yarn:
yarn add pg && yarn add pg-connection-string
With npm:
npm install pg && npm install pg-connection-string
Add package-lock.json
to the end of the .gitignore
file at the root of the Strapi project:
# path: ./.gitignore
package-lock.json
Verify that all of the new and modified files are saved locally.
Commit the project to a local repository:
git init
git add .
git commit -m "commit message"
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.
Use the following OS-specific installation instructions to install the Heroku CLI tool:
On a Ubuntu-based computer:
Run the following from a terminal:
curl https://cli-assets.heroku.com/install-ubuntu.sh | sh
On a Mac:
or install via Homebrew:
brew tap heroku/brew && brew install heroku
On Windows:
Download the appropriate installer for a Windows installation:
Login to Heroku from the CLI, following the command-line instructions:
heroku login
Create a new Heroku project by running the following command in the root directory of the Strapi project:
# path: ./my-project/
heroku create
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
The local development environment is now set up and configured to work with Heroku.
The following command creates and connects a PostgreSQL database with the Heroku project. Consult the Heroku documentation for database plan names and costs.
# path: ./my-project/
heroku addons:create heroku-postgresql:<PLAN_NAME>
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
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
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.
Set new secrets (Mac and Linux)
The following openssl
commands generate random new secrets (Mac and Linux only) and set the config values:
heroku config:set APP_KEYS=$(openssl rand -base64 32)
heroku config:set API_TOKEN_SALT=$(openssl rand -base64 32)
heroku config:set ADMIN_JWT_SECRET=$(openssl rand -base64 32)
heroku config:set JWT_SECRET=$(openssl rand -base64 32)
heroku config:set MY_HEROKU_URL=$(heroku info -s | grep web_url | cut -d= -f2)
heroku config:set NODE_ENV=production
Transfer existing secrets (Mac and Linux)
The following commands transfer the local secrets in the .env
file to the remote instance:
heroku config:set APP_KEYS=$(cat .env | grep APP_KEYS | cut -d= -f2-)
heroku config:set API_TOKEN_SALT=$(cat .env | grep API_TOKEN_SALT | cut -d= -f2)
heroku config:set ADMIN_JWT_SECRET=$(cat .env | grep ADMIN_JWT_SECRET | cut -d= -f2)
heroku config:set JWT_SECRET=$(cat .env | grep -w JWT_SECRET | cut -d= -f2)
heroku config:set MY_HEROKU_URL=$(heroku info -s | grep web_url | cut -d= -f2)
heroku config:set NODE_ENV=production
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
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
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.
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, 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
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, 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.