33 KiB
Deployment
Strapi gives you many possible deployment options for your project or application. Strapi can be deployed on traditional hosting servers or services such as Heroku, AWS, Azure and others. The following documentation covers how to develop locally with Strapi and deploy Strapi with various hosting options.
(Deploying databases along with Strapi is covered in the Databases Guide.)
Table of contents:
Configuration
#1 - Configure
Update the production
settings with the IP and domain name where the project will be running.
Path — ./config/environments/production/server.json
.
{
"host": "domain.io", // IP or domain
"port": 1337,
"autoReload": {
"enabled": false
},
"admin": {
"path": "/dashboard" // We highly recommend to change the default `/admin` path for security reasons.
}
}
In case your database is not running on the same server, make sure that the environment of your production
database (./config/environments/production/database.json
) is set properly.
If you are passing a number of configuration item values via environment variables which is always encouraged for production environment to keep application stateless, checkout the section for Dynamic Configuration. Here is a hint on how to do it for production, for the configuration mentioned above:
Path — ./config/environments/production/server.json
.
{
"host": "${process.env.APP_HOST || '127.0.0.1'}"
"port": "${process.env.NODE_PORT || 1337}",
"autoReload": {
"enabled": false
},
"admin": {
"path": "/dashboard" // We highly recommend to change the default `/admin` path for security reasons.
}
}
⚠️ If you changed the path to access to the administration, the step #2 is required.
#2 - Setup (optional)
Run this following command to install the dependencies and build the project with your custom configurations.
cd /path/to/the/project
npm run setup
::: note
To display the build logs use the --debug option npm run setup --debug
.
:::
#3 - Launch the server
Run the server with the production
settings.
NODE_ENV=production npm start
::: warning We highly recommend to use pm2 to manage your process. :::
Advanced configurations
If you want to host the administration on another server than the API, please take a look at this dedicated section.
Digital Ocean
This is a step-by-step guide for deploying a Strapi project to Digital Ocean. Databases can be on a Digital Ocean Droplet or hosted externally as a service. Prior to starting this guide, you should have created a Strapi project.
Digital Ocean Install Requirements
- You must have a free Digital Ocean account before doing these steps.
Create a "Droplet"
Digital Ocean calls a virtual private server, a Droplet. You need to create a new Droplet
to host your Strapi project.
- Log in to your Digital Ocean account.
Create a Droplet
by clicking onNew Droplet
. Choose these options:
- Ubuntu 18.04 x64
- STARTER
Standard
- Choose an appropriate pricing plan. For example, pricing:
$5/mo
(Scroll to the left) - Choose a
datacenter
region nearest your audience, for example,New York
. - OPTIONAL: Select additional options, for example,
[x] IPv6
. - Add your SSH key NOTE: We recommend you
add your SSH key
for better security.- In your terminal, use
pbcopy < ~/.ssh/id_rsa.pub
to copy your existing SSH public key, on your development computer, to the clipboard. - Click on
New SSH Key
and paste in yourSSH Key
.Name
this SSH key and thenSave
. (Additional instructions on creating and using SSH Keys can be found here.)
- In your terminal, use
- OPTIONAL:
Choose a hostname
or leave as-is. - Click the green
Create
button.
Digital Ocean will create your Droplet and indicate the progress with a percentage bar. Once this is complete, you may continue to the next steps.
Setup production server and install Node.js
These next steps will help you to set up a production server and set up a non-root user for managing your server.
Follow the official Digital Ocean docs for initial server set-up using Ubuntu 18.04. These docs will have you complete the following actions:
- Logging and set up root user access to your server with SSH.
- Creating a new user.
- Granting Administrative Privileges to the new user.
- Setting up a basic firewall.
- Giving your regular user access to the server with SSH key authentication.
Next, install Node.js
:
- You will install
Node.js
using the instructions in section Install Node using a PPA from the official Digital Ocean docs for installing a production ready Node.js server.
After completing the steps to install Node.js, NPM and the "build-essential package", you will manually change npm's default directory. The following steps are based on how to resolve access permissions from npmjs.com:
- Create a
.npm-global
directory and set the path to this directory fornode_modules
cd ~
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
- Create (or modify) a
~/.profile
file and add this line:
sudo nano ~/.profile
Add this line.
export PATH=~/.npm-global/bin:$PATH
- Lastly, update your system variables:
source ~/.profile
You are now ready to continue to the next section.
Install and Configure Git versioning on your server
A convenient way to maintain your Strapi application and update it during and after initial development is to use Git. In order to use Git, you will need to have it installed on your Droplet. Droplets should have Git installed by default, so you will first check if it is installed and if it is not installed, you will need to install it.
The last step is to configure Git on your server.
- Check to see if
Git
is installed, if you see agit version 2.x.x
then you do haveGit
installed. Check with the following command:
git --version
-
OPTIONAL: Install Git. NOTE: Only do if not installed, as above. Please follow these directions on how to install Git on Ubuntu 18.04.
-
Complete the global username and GitHub settings: Setting up Git
After installing and configuring Git on your Droplet. Please continue to the next step, installing a database.
Install the database for your project
Digital Ocean has excellent documentation regarding the installation and use of the major databases that work with Strapi. The previous steps above should all be completed prior to continuing. You can find links, and any further instructions, to each database guide below:
:::: tabs cache-lifetime="10" :options="{ useUrlFragment: false }"
::: tab "PostgreSQL" id="postgreSQL-ubuntu"
- Install PostgresSQL on Ubuntu 18.04(Through Step 4 - Creating a New Database).
Complete the steps to install PostgreSQL, add a user and create a database.
- In order to connect to a PostgreSQL database with Strapi, it needs either to have a password, or specifically state there is no password by noting a empty string. Follow these commands from your terminal to
alter
theuser
you created andadd a password
:
sudo -u postgres psql //only necessary if you switched away from the postgres@ user
[sudo] password for your-name:
psql (10.8 (Ubuntu 10.8-0ubuntu0.18.04.1))
Type "help" for help.
psql
postgres=# ALTER USER your-name PASSWORD 'password';
ALTER ROLE
postgres=# \q
exit
-
Optional: If in Development, your Strapi project is uses SQLite, you will need to install a dependency package called
pg
:- On your Development computer:
Path: ./my-project/
npm install pg --save
Note: The
pg
package is automatically installed locally if you choosePostgreSQL
as the initial database choice when you first set-up Strapi.
You will need the database name, username and password to continue to the next step of configuring that database.json file.
Local Development Configuration
- You must have Git installed and set-up locally.
- You must have created a repository for your Strapi project and have your development project initilized to this repository.
In your code editor, you will need to edit a file called database.json
. Replace the contents of the file with the following, but change the username
, password
and database
to match your installation.
Path: ./config/environments/production
{
"defaultConnection": "default",
"connections": {
"default": {
"connector": "strapi-hook-bookshelf",
"settings": {
"client": "postgres",
"host": "localhost",
"port": 5432,
"username": "your-name",
"password": "password",
"database": "strapi"
},
"options": {}
}
}
}
You are now ready to push these changes to Github:
git add .
git commit -m "Configured production/database.json"
git push
Please continue to the next section, Deploy from GitHub.
:::
::::
Deploy from Github
You will next deploy your Strapi project to your Droplet by cloning it from GitHub
.
From your terminal, logged in as your non-root user
to your Droplet:
cd ~
git clone https://github.com/your-name/your-project-repo.git
Next, navigate to the my-project
folder, the root for Strapi. You will now need to run npm install
to install the packages for your project.
Path: ./my-project/
cd ./my-project/
npm install
Strapi uses Port: 1337
by default. You will need to configure your ufw firewall
to allow access to this port:
cd ~
sudo ufw allow 1337/tcp
sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup
Your Strapi project is now installed on your Droplet.
OPTIONAL: You may see your project and set-up your first administrator user, by doing the following:
- Navigate to the Strapi project folder.
Path: ./my-project/
. Run the following command from within the Strapi project root:
Path: ./my-project/
NODE_ENV=production npm run start
> my-project@0.1.0 start /home/path-to-your-project-folder/my-project
> node server.js
[2019-05-20T14:06:01.553Z] info Time: Mon May 20 2019 14:06:01 GMT+0000 (Coordinated Universal Time)
[2019-05-20T14:06:01.555Z] info Launched in: 2623 ms
[2019-05-20T14:06:01.555Z] info Environment: production
[2019-05-20T14:06:01.555Z] info Process PID: 7286
[2019-05-20T14:06:01.556Z] info Version: 3.0.0-alpha.25.2 (node v10.15.3)
[2019-05-20T14:06:01.556Z] info To shut down your server, press <CTRL> + C at any time
[2019-05-20T14:06:01.557Z] info ☄️ Admin panel: http://localhost:1337/admin
[2019-05-20T14:06:01.557Z] info ⚡️ Server: http://localhost:1337
Minimumly, create an admin user.
You will next need to install and configure PM2 Runtime.
Install and configure PM2 Runtime
PM2 Runtime allows you to keep your Strapi project alive and to reload it without downtime.
Ensure you are logged in as a non-root user. You will install PM2 globally:
npm install pm2@latest -g
Navigate to your Strapi Project folder and use the following command to set the environment variable to production and start pm2
:
Path: ./my-project/
NODE_ENV=production pm2 start --name="strapi" server.js
Follow the steps below to have your app launch on system startup. (NOTE: These steps are modified from the Digital Ocean documentation for setting up PM2.)
- Generate and configure a startup script to launch PM2, it will generate a Startup Script to copy/paste, do so:
$ cd ~
$ pm2 startup systemd
[PM2] Init System found: systemd
[PM2] To setup the Startup Script, copy/paste the following command:
sudo env PATH=$PATH:/usr/bin /home/your-name/.npm-global/lib/node_modules/pm2/bin/pm2 startup systemd -u your-name --hp /home/your-name
- Copy/paste the generated command:
$ sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u your-name --hp /home/your-name
[PM2] Init System found: systemd
Platform systemd
. . .
[PM2] [v] Command successfully executed.
+---------------------------------------+
[PM2] Freeze a process list on reboot via:
$ pm2 save
[PM2] Remove init script via:
$ pm2 unstartup systemd
- Next,
Save
the new PM2 process list and environment. ThenStart
the service withsystemctl
:
pm2 save
[PM2] Saving current process list...
[PM2] Successfully saved in /home/your-name/.pm2/dump.pm2
- OPTIONAL: You can test to see if the script above works whenever your system reboots with the
sudo reboot
command. You will need to login again with your non-root user and then runpm2 list
andsystemctl status pm2-your-name
to verify everything is working.
In the sections to follow, are a few recommended additional actions to make developing your project more efficient
The ecosystem.config.js file
-
You will need to configure an
ecosystem.config.js
file. It will be used bypm2
to restart your project whenever any changes are made to files within the Strapi file system itself (such as when an update arrives from GitHub). You can read more about this file here.- You will need to open your
nano
editor and thencopy/paste
the following:
- You will need to open your
cd ~
pm2 init
sudo nano ecosystem.config.js
- Next, replace the boilerplate content in the file, with the following:
module.exports = {
apps: [
{
name: 'your-app-name',
cwd: '/home/your-name/my-strapi-project/my-project',
script: 'server.js',
env: {
NODE_ENV: 'production',
},
},
],
};
pm2
is now set-up to use an econsystem.config.js
to manage restarting your application upon changes. This is a recommended best practice. Continue below to configure the webhook
.
Set up a webhook
Providing that your project is set-up on GitHub, you will need to configure your Strapi Project Repository with a webhook. The following articles provide additional information to the steps below: GitHub Creating Webhooks Guide and Digital Ocean Guide to GitHub WebHooks.
-
You will need to access the
Settings
tab for yourStrapi Project Repository
:- Navigate and click to
Settings
for your repository. - Click on
Webhooks
, then clickAdd Webhook
. - The fields are filled out like this:
- Payload URL: Enter
http://your-ip-address:8080
- Content type: Select
application/json
- Which events would you like to trigger this webhook: Select
Just the push event
- Secret: Enter
YourSecret
- Active: Select the checkbox
- Payload URL: Enter
- Review the fields and click
Add Webhook
.
- Navigate and click to
-
Next, you need to create a
Webhook Script
on your server. These commands create a new file calledwebhook.js
which will hold two variables:
cd ~
mkdir NodeWebHooks
cd NodeWebHooks
sudo nano webhook.js
- In the
nano
editor, copy/paste the following script, but make sure to replaceyour_secret_key
andrepo
with the values that correspond to your project, then save and exit. NOTE: Earlier in this guide, there is a optional recommended step to create anecosystem.config.js
file to manage your application restarting function.
(This script creates a variable called PM2_CMD
which is used after pulling from GitHub to update your project. The script first changes to the home directory and then runs the variable PM2_CMD
as pm2 restart strapi
. If the project uses the ecosystem.config.js
keep your ecosystem.config.js
as the point of starting your application and use the alternative below. PLEASE SEE COMMENTS IN THE CODE.)
var secret = 'your_secret_key';
var repo = '~/path-to-your-repo/';
const http = require('http');
const crypto = require('crypto');
const exec = require('child_process').exec;
// Use this command if you DID NOT create the ecosystem.config.js file
const PM2_CMD = 'pm2 restart strapi';
// Use this command if you DID create the ecosystem.config.js file and comment out/delete the above line.
// const PM2_CMD = 'cd ~ && pm2 startOrRestart ecosystem.config.js';
http
.createServer(function(req, res) {
req.on('data', function(chunk) {
let sig =
'sha1=' +
crypto
.createHmac('sha1', secret)
.update(chunk.toString())
.digest('hex');
if (req.headers['x-hub-signature'] == sig) {
exec(
`cd ${repo} && git pull && ${PM2_CMD}`,
(error, stdout, stderr) => {
if (error) {
console.error(`exec error: ${error}`);
return;
}
console.log(`stdout: ${stdout}`);
console.log(`stderr: ${stderr}`);
},
);
}
});
res.end();
})
.listen(8080);
- Allow the port to communicate with outside web traffic for
port 8080
:
sudo ufw allow 8080/tcp
sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup
Earlier you setup pm2
to start the services (your Strapi project) whenever the Droplet reboots or is started. You will now do the same for the webhook
script.
-
Install the webhook as a
Systemd
service- Run
echo $PATH
and copy the output for use in the next step.
- Run
echo $PATH
/home/your-name/.npm-global/bin:/home/your-name/bin:/home/your-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
- Create a
webhook.service
file:
cd ~
sudo nano /etc/systemd/system/webhook.service
- In the
nano
editor, copy/paste the following script, but make sure to replaceyour-name
in two places with your username, then save and exit:
[Unit]
Description=Github webhook
After=network.target
[Service]
Environment=PATH=/PASTE-PATH_HERE
Type=simple
User=your-name
ExecStart=/usr/bin/nodejs /home/your-name/NodeWebHooks/webhook.js
Restart=on-failure
[Install]
WantedBy=multi-user.target
- Enable and start the new service so it starts when the system boots:
sudo systemctl enable webhook.service
sudo systemctl start webhook
- Check the status of the webhook:
sudo systemctl status webhook
- You may test your webhook by following the instructions here.
Further steps to take
- You can add a domain name or use a subdomain name for your Strapi project, you will need to install NGINX and configure it.
- To install SSL, you will need to install and run Certbot by Let's Encrypt.
- Set-up Nginx with HTTP/2 Support for Ubuntu 18.04.
Your Strapi
project has been installed on a Digital Ocean Droplet using Ubuntu 18.04.
Heroku
This is a step-by-step guide for deploying a Strapi project to Heroku. Databases that work well with Strapi and Heroku are provided instructions on how to get started.
Heroku Install Requirements
- You must have Git installed and set-up locally.
- You must have a free Heroku account before doing these steps.
If you already have the Heroku CLI installed locally on your computer. Skip to Login to Heroku.
1. Heroku CLI Installation
Download and install the Heroku CLI
for your operating system:
:::: tabs cache-lifetime="10" :options="{ useUrlFragment: false }"
::: tab "macOS" Download the installer
Also available via Homebrew:
brew tap heroku/brew && brew install heroku
:::
::: tab "Ubuntu" Run the following from your terminal:
sudo snap install --classic heroku
:::
::: tab "Windows" Download the appropriate installer for your Windows installation:
64-bit installer 32-bit installer :::
::::
2. Login to Heroku from your CLI
Next, you need to login to Heroku from your computer.
heroku login
Follow the instructions and return to your command line.
3. Create a new project (or use an existing one)
Create a new Strapi project (if you want to deploy an existing project go to step 4).
::: warning NOTE
If you plan to use MongoDB with your project, refer to the create a Strapi project with MongoDB section of the documentation then, jump to step 4.
:::
Path: ./
strapi new my-project --quickstart
Note: When you use --quickstart
to create a Strapi project locally, a SQLite database is used which is not compatible with Heroku. Therefore, another database option must be chosen.
4. Update .gitignore
Add the following line at end of .gitignore
:
Path: ./my-project/.gitignore
package-lock.json
Even if it is usually recommended to version this file, it may create issues on Heroku.
5. Init a Git repository and commit your project
Init the Git repository and commit yoru project.
Path: ./my-project/
cd my-project
git init
git add .
git commit -am "Initial Commit"
6. Create a Heroku project
Create a new Heroku project.
Path: ./my-project/
heroku create
(You can use heroku create custom-project-name
, to have Heroku create a custom-project-name.heroku.com
URL. Otherwise, Heroku will automatically generating a random project name (and URL) for you.)
::: warning NOTE If you have a Heroku project app already created. You would use the following step to initialize your local project folder:
Path: ./my-project/
heroku git:remote -a your-heroku-app-name
:::
Your local development environment is now set-up and configured to work with Heroku. You have a new Strapi project and a new Heroku app ready to be configured to work with a database and with each other.
7. Heroku Database set-up
Below you will find database options when working with Heroku. Please choose the correct database (e.g. PostgreSQL, MongoDB, etc.) and follow those instructions.
:::: tabs cache-lifetime="10" :options="{ useUrlFragment: false }"
::: tab "PostgreSQL" id="heroku-postgresql"
Heroku Postgres
Follow these steps to deploy your Strapi app to Heroku using PostgreSQL:
1. Install the Heroku Postgres addon for using Postgres.
To make things even easier, Heroku provides a powerful addon system. In this section, you are going to use the Heroku Postgres addon, which provides a free "Hobby Dev" plan. If you plan to deploy your app in production, it is highly recommended to switch to a paid plan.
Path: ./my-project/
heroku addons:create heroku-postgresql:hobby-dev
2. Retrieve database credentials
The add-on automatically exposes the database credentials into a single environment variable accessible by your app. To retrieve it, type:
Path: ./my-project/
heroku config
This should print something like this: DATABASE_URL: postgres://ebitxebvixeeqd:dc59b16dedb3a1eef84d4999sb4baf@ec2-50-37-231-192.compute-2.amazonaws.com: 5432/d516fp1u21ph7b
.
(This url is read like so: *postgres:// USERNAME : PASSWORD @ HOST : PORT : DATABASE_NAME*)
3. Set environment variables
Strapi expects a variable for each database connection configuration (host, username, etc.). So, from the url above, you have to set several environment variables in the Heroku config:
heroku config:set DATABASE_USERNAME=ebitxebvixeeqd
heroku config:set DATABASE_PASSWORD=dc59b16dedb3a1eef84d4999a0be041bd419c474cd4a0973efc7c9339afb4baf
heroku config:set DATABASE_HOST=ec2-50-37-231-192.compute-2.amazonaws.com
heroku config:set DATABASE_PORT=5432
heroku config:set DATABASE_NAME=d516fp1u21ph7b
Note: Please replace these above values with the your actual values.
4. Update your database config file
Replace the contents of database.json
with the following:
Path: ./config/environments/production/database.json
.
{
"defaultConnection": "default",
"connections": {
"default": {
"connector": "strapi-hook-bookshelf",
"settings": {
"client": "postgres",
"host": "${process.env.DATABASE_HOST}",
"port": "${process.env.DATABASE_PORT}",
"database": "${process.env.DATABASE_NAME}",
"username": "${process.env.DATABASE_USERNAME}",
"password": "${process.env.DATABASE_PASSWORD}",
"ssl": true
},
"options": {}
}
}
}
5. Install the pg
node module
Unless you originally installed Strapi with PostgreSQL, you need to install the pg node module.
Path: ./my-project/
npm install pg --save
:::
::: tab "MongoDB" id="heroku-mongodb"
MongoDB Atlas
(Using Strapi and MongoDB requires different set-up and different configuration steps. You cannot use --quickstart
to develop a MongoDB
Strapi project.)
Please follow these steps the deploy a Strapi app with MongoDB on Heroku.
You must have completed the steps to use Strapi with MongoDB Atlas in production.
1. Set environment variables
When you set-up your MongoDB Atlas database you created and noted the five key/value pairs that correspond to your MongoDB Atlas database. These five keys are: DATABASE_NAME
, DATABASE_USERNAME
, DATABASE_PASSWORD
, DATABASE PORT
, and DATABASE_HOST
.
Strapi expects a variable for each database connection detail (host, username, etc.). So, from MongoDB Atlas, you have to set the environment variables in the Heroku config (for DATABASE_HOST you need to surround the URL with "", and set DATABASE_PORT to nothing):
heroku config:set DATABASE_USERNAME=paulbocuse
heroku config:set DATABASE_PASSWORD=mySecretPassword
heroku config:set DATABASE_HOST="stapi-mongo-heroku-shard-00-00-fty6c.mongodb.net:27017,strapi-mongo-heroku-shard-00-01-fty6c.mongodb.net:27017,strapi-mongo-heroku-shard-00-02-fty6c.mongodb.net:27017/test?ssl=true&replicaSet=strapi-mongo-heroku-shard-0&authSource=admin&retryWrites=true"
heroku config:set DATABASE_PORT=
heroku config:set DATABASE_NAME=strapi-mongo-heroku
Note: Please replace these above values with the your actual values.
2. Update your database config file
Replace the contents of database.json
with the following:
Path: ./config/environments/production/database.json
.
{
"defaultConnection": "default",
"connections": {
"default": {
"connector": "strapi-hook-mongoose",
"settings": {
"client": "mongo",
"host": "${process.env.DATABASE_HOST}",
"port": "${process.env.DATABASE_PORT}",
"database": "${process.env.DATABASE_NAME}",
"username": "${process.env.DATABASE_USERNAME}",
"password": "${process.env.DATABASE_PASSWORD}"
},
"options": {
"ssl": true
}
}
}
}
::::
8. Commit your changes
Path: ./my-project/
git commit -am "Update database config"
9. Deploy
Path: ./my-project/
git push heroku master
The deployment may take a few minutes. At the end, logs will display the url of your project (e.g. https://mighty-taiga-80884.herokuapp.com
). You can also open your project using the command line:
Path: ./my-project/
heroku open
If you see the Strapi Welcome page, you have correctly set-up, configured and deployed your Strapi project on Heroku. You will now need to set-up your admin user
as the production database is brand-new (and empty).
You can now continue with the Tutorial - Creating an Admin User, if you have any questions on how to proceed.
::: warning NOTE For security reasons, the Content Type Builder plugin is disabled in production. To update content structure, please make your changes locally and deploy again. :::
Project updates
When Strapi is deployed to Heroku, Heroku sets the environment variable to NODE_ENV=production
. In production mode
Strapi disables the content-type builder (for security reasons). Additionally, if you wanted to change the default production mode in Heroku, it wouldn't work as the file system is temporary. Strapi writes files to the server when you update the content-types and these updates would disappear when Heroku restarts the server.
Therefore, modifications that require writing to model creation or other json files, e.g. creating or changing content-types, require that you make those changes on your dev environment and then push the changes to Heroku.
As you continue developing your application with Strapi, you may want to use version control, or you can continue to use Git push heroku master
to commit and push changes to Heroku directly.
Path: ./my-project/
git add .
git commit -am "Changes to my-project noted"
git push heroku master
heroku open
Docker
::: tip You can also deploy using Docker :::
The method below describes regular deployment using the built-in mechanisms.