# Amazon AWS
✋ CAUTION
This third-party deployment guide might not be up-to-date with Strapi v4. Contributions (opens new window) are most welcome.
This is a step-by-step guide for deploying a Strapi project to Amazon AWS EC2 (opens new window). This guide will connect to an Amazon AWS RDS (opens new window) for managing and hosting the database. Optionally, this guide will show you how to connect host and serve images on Amazon AWS S3 (opens new window).
Prior to starting this guide, you should have created a Strapi project, to use for deploying on AWS. And have read through the configuration section.
# Amazon AWS Install Requirements and creating an IAM non-root user
- You must have an Amazon AWS (opens new window) account before doing these steps.
Best practices for using AWS Amazon services state to not use your root account user and to use instead the IAM (AWS Identity and Access Management) service (opens new window). Your root user is therefore only used for a very few select tasks (opens new window). For example, for billing, you create an Administrator user and Group for such things. And other, more routine tasks are done with a regular IAM User.
# 1. Follow these instructions for creating your Administrator IAM Admin User and Group (opens new window)
- Login as root.
- Create Administrator role.
# 2. Next, create a regular user for the creation and management of your Strapi project
- Copy your IAM Users sign-in link found here: IAM Console (opens new window) and then log out of your root user and log in to your administrator user you just created.
- Return to the IAM Console by
searching for IAM
and clicking or going here: IAM Console (opens new window). - Click on
Users
, in the left hand menu, and then clickAdd User
:- In the Set user details screen:
- Provide a User name.
- Access Type: Check both
Programmatic access
andAWS Management Console access
. Autogenerate a password
or clickCustom password
and provide one.- OPTIONAL: For simplicity,
uncheck
the Require password reset. - Click
Next: Permissions
.
- In the Set Permissions screen, do the following:
- Click
Create group
, name it, e.g.Developers
, and then choose appropriate policies under Policy Name:- search for
ec2
and checkAmazonEC2FullAccess
- search for
RDS
and checkAmazonRDSFullAccess
- search for
s3
and checkAmazonS3FullAccess
- Click
Create group
- search for
- Click to
Add user to group
and check theDevelopers
group, to add the new user. - Click
Next: Tags
.
- Add tags (optional)
- This step is optional and based on your workflow and project scope.
- Click
Next: Review
.
- Review
- Review the information and ensure it is correct. Use
Previous
to correct anything. - Click
Create user
.
- Success - These are very IMPORTANT CREDENTIALS If you do not do these steps you will have to reset your
Access key ID
andSecret access key
later.
Download the .csv file
and store it in a safe place. This contains the user name, login link, Access key ID and Secret access key.- OPTIONAL: Add these credentials to your *Password manager**.
- Click on the
AWS Management Console Access sign-in link
. This will log you out ofAdministrator
.
# 3. Log into
your AWS Management Console as your regular user
You may now proceed to the next steps.
# Additional IAM User Resources
- IAM Best Practices (opens new window).
- Instructions to reset Access key ID and Secret access key (opens new window).
# Launch an EC2 virtual machine
Amazon calls a virtual private server, a virtual server or Amazon EC2 instance. To use this service you will Launch Instance
. In this section, you will establish IAM credentials, launch a new instance and set-up primary security rules.
# 1. From your AWS Management Console and as your regular user
Find Services
, search forec2
and click onEC2, Virtual Servers in the Cloud
# 2. Select Appropriate Region
In the top menu, near your IAM Account User name, select, from the dropdown, the most appropriate region to host your Strapi project. For example, US East (N.Virginia)
or Asia Pacific (Hong Kong)
. You will want to remember this region for configuring other services on AWS and serving these services from the same region.
# 3. Click on the orange Launch Instance
button
Select
Ubuntu Server 18.04 LTS (HVM), SSD Volume Type- Ensure
General purpose
+t2.small
ischecked
.💡 TIP
t2.small
is the smallest instance type in which Strapi runs.t2.nano
andt2.micro
DO NOT work. At the moment, deploying the Strapi Admin interface requires more than 1g of RAM. Therefore, t2.small or larger instance is needed. - Click the grey
Next: Configure Instance Details
andNext: Add Storage
- In the Step 4: Add Storage verify the
General Purpose SSD (gp2)
, then clickNext: Add tags
. - In the Step 5: Add Tags, add tags to suit your project or leave blank, then click
Next: Configure Security Group
. - In the Step 6: Configure Security Group, configure the
security settings
as follows:- Assign a security group: Check as
Create a new security group
- Security group name: Name it, e.g.
strapi
- Description: Write a short description, e.g.
strapi instance security settings
- You should have a rule: Type:
SSH
, Protocol:TCP
, Port Range22
, Source:0.0.0.0/0
(all IP addresses). If not, add it. - Click the grey
Add rule
to add each of these rules:- Type:
SSH
, Protocol:TCP
, Port Range22
, Source:::/0
- Type:
HTTP
, Protocol:TCP
, Port Range80
, Source:0.0.0.0/0, ::/0
- Type:
HTTPS
, Protocol:TCP
, Port Range443
, Source:0.0.0.0/0, ::/0
- Type:
Custom TCP Rule
, Protocol:TCP
, Port Range1337
, Source:0.0.0.0/0
Description:Strapi for Testing Port
These rules are basic configuration and security rules. You may want to tighten and limit these rules based on your own project and organizational policies.💡 TIP
After setting up your Nginx rules and domain name with the proper aliases, you will need to delete the rule regarding port 1337 as this is for testing and setting up the project - not for production.
- Type:
- Assign a security group: Check as
- Click the blue
Review and Launch
button. - Review the details, in the Step 7: Review Instance Launch, then click the blue
Launch
button. Now, you need to select an existing key pair or create a new key pair. To create a new key pair, do the following:- Select the dropdown option
Create a new key pair
. - Name your the key pair name, e.g.
ec2-strapi-key-pair
✋ CAUTION
Download the private key file (.pem file). This file is needed, so note where it was downloaded.
- After downloading the file, click the blue
Launch Instances
button.
- Select the dropdown option
Your instance is now running. Continue to the next steps.
# Install a PostgreSQL database on AWS RDS
Amazon calls their database hosting services RDS. Multiple database options exist and are available. In this guide, PostgreSQL is used as the example, and the steps are similar for each of the other database that are supported by Strapi. (MySQL, PostgreSQL, MariaDB, SQLite). You will set-up an RDS instance to host your postgresql
database.
💡 TIP
Amazon RDS does NOT have a completely free evaluation tier. After finishing this guide, if you are only testing, please remember to delete the database (opens new window). Otherwise, you will incur charges.
# 1. Navigate to the AWS RDS Service
In the top menu, click on Services
and do a search for rds
, click on RDS, Managed Relational Database Service
.
# 2. Select your region
In the top menu bar, select the region that is the same as the EC2 instance, e.g. EU (Paris)
or US East (N. Virgina)
.
# 3. Create the database
Click the orange Create database
button.
Follow these steps to complete installation of a PostgreSQL
database:
- Engine Options: Click on
PostgreSQL
, version PostgreSQL 10.x-R1 - Templates: Click on
Free Tier
. - Settings
- DB instance identifier Give a name to your database, e.g.
strapi-database
- Credential Settings: This is your
psql
database username and password.- Master username: Keep as
postgres
, or change (optional) Uncheck
Auto generate a password, and then type in a new secret password.
- Master username: Keep as
- DB instance identifier Give a name to your database, e.g.
- Connectivity, and Additional connectivity configuration: Set
Publicly accessible
toYes
. - OPTIONAL: Review any further options (DB Instance size, Storage, Connectivity), and modify to your project needs.
- You need to give you Database a name. Under Additional configuration:
- Additional configuration, and then Initial database name: Give your database a name, e.g.
strapi
.
- Additional configuration, and then Initial database name: Give your database a name, e.g.
- Review the rest of the options and click the orange,
Create database
button.
After a few minutes, you may refresh your page and see that your database has been successfully created.
# Configure S3 for image hosting
Amazon calls cloud storage services S3. You create a bucket, which holds the files, images, folders, etc... which then can be accessed and served by your application. This guide will show you how to use Amazon S3 to host the images for your project.
# 1. Navigate to the Amazon S3
In the top menu, click on Services
and do a search for s3
, click on Scalable storage in the cloud
.
# 2. Create the bucket
Click on the blue Create bucket
button:
- Give your bucket a unique name, under Bucket name, e.g.
my-project-name-images
. - Select the most appropriate region, under Region, e.g.
EU (Paris)
orUS East (N. Virgina)
. - Click
Next
. - Configure any appropriate options for your project in the Configure Options page, and click
next
. - Under Block public access:
- Uncheck
Block all public access
and set the permissions as follows:Uncheck
Block new public ACLs and uploading public objects (Recommended)Uncheck
Block public access to buckets and objects granted through any access control lists (ACLs)Check
Block public access to buckets and objects granted through new public bucket policiesCheck
Block public and cross-account access to buckets and objects through any public bucket policies
- Select
Do not grant Amazon S3 Log Delivery group write access to this bucket
.
- Uncheck
- Click
Next
. - Review and click
Create bucket
.
# Configure EC2 as a Node.js server
You will set-up your EC2 server as a Node.js server. Including basic configuration and Git.
You will need your EC2 ip address:
- In the
AWS Console
, navigate to theAWS EC2
. In the top menu, click onServices
and do a search forec2
, click onVirtual Servers in the cloud
. - Click on
1 Running Instance
and note theIPv4 Public OP
address. E.g.34.182.83.134
.
# 1. Setup the .pem
file
- You downloaded, in a previous step, your
User
.pem file. e.g.ec2-strapi-key-pair.pem
. This needs to be included in each attempt toSSH
into yourEC2 server
. Move your.pem
file to~/.ssh/
, follow these steps: - On your local machine, navigate to the folder that contains your .pem file. e.g.
downloads
- Move the .pem file to
~/.ssh/
and set file permissions:Path:./path-to/.pem-file/
mv ec2-strapi-key-pair.pem ~/.ssh/
chmod 400 ~/.ssh/ec2-strapi-key-pair.pem
# 2. Log in to your server as the default ubuntu
user:
💡 TIP
In the future, each time you log into your EC2
server, you will need to add the path to the .pem file, e.g. ssh -i ~/.ssh/ec2-strapi-key-pair.pem ubuntu@12.123.123.11
.
ssh -i ~/.ssh/ec2-strapi-key-pair.pem ubuntu@12.123.123.11
Welcome to Ubuntu 18.04.2 LTS (GNU/Linux 4.15.0-1032-aws x86_64)
...
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.
ubuntu@ip-12.123.123.11:~$
# 3. Install Node.js with npm:
Strapi currently supports Node.js v12.x.x
. The following steps will install Node.js onto your EC2 server.
cd ~
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
...
sudo apt-get install nodejs
...
node -v && npm -v
The last command node -v && npm -v
should output two versions numbers, eg. v12.x.x, 6.x.x
.
# 4. Create and change npm's default directory.
The following steps are based on how to resolve access permissions from npmjs.com (opens new window):
- 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 these lines at the bottom of the ~/.profile
file.
# set PATH so global node modules install without permission issues
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 (opens new window). In order to use Git, you will need to have it installed on your EC2 instance. EC2 instances 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 next step is to configure Git on your server.
# 1. Check to see if Git
is installed
If you see a git version 2.x.x
then you do have Git
installed. Check with the following command:
git --version
# 2. OPTIONAL: Install Git.
💡 TIP
Only do if not installed, as above. Please follow these directions on how to install Git on Ubuntu 18.04 (opens new window).
# 3. Configure the global username and email settings: Setting up Git - Your Identity (opens new window)
After installing and configuring Git on your EC2 instance. Please continue to the next step.
# Prepare and clone Strapi project to server
These instructions assume that you have already created a Strapi project, and have it in a GitHub repository.
You will need to update the database.json
file to configure Strapi to connect to the RDS
database. And you will need to install an npm package called pg
locally on your development server.
💡 TIP
The pg
package install is only necessary if you are using PostgresSQL as your database.
# 1. Install pg
in your Strapi project.
On your development machine, navigate to your Strapi project root directory:
Path: ./my-project/
npm install pg
# 2. Edit the ./config/database.js
file.
Copy/paste the following:
# 3. Install the Strapi AWS S3 Upload Provider:
Path: ./my-project/
.
npm install @strapi/provider-upload-aws-s3
To enable and configure the provider, create or edit the file at ./config/plugins.js
.
Checkout the documentation about using an upload provider here.
# 4. Push your local changes to your project's GitHub repository.
git add .
git commit -m 'Installed pg, aws-S3 upload provider and updated the config files'
git push
# 5. Deploy from GitHub
You will next deploy your Strapi project to your EC2 instance by cloning it from GitHub.
From your terminal and logged into your EC2 instance as the ubuntu
user:
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 need to run npm install
to install the packages for your project.
Path: ./my-project/
cd ./my-project/
npm install
NODE_ENV=production npm run build
Next, you need to install PM2 Runtime and configure the ecosystem.config.js
file
# 6. Install PM2 Runtime
PM2 Runtime (opens new window) 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
Now, you will need to configure an ecosystem.config.js
file. This file will set env
variables that connect Strapi to your database. It will also be used to restart your project whenever any changes are made to files within the Strapi file system itself (such as when an update arrived from Github). You can read more about this file here (opens new window).
- You will need to open your
nano
editor and thencopy/paste
the following:
cd ~
pm2 init
sudo nano ecosystem.config.js
- Next, replace the boilerplate content in the file, with the following:
You can also set your environment variables in a .env
file in your project like so:
DATABASE_HOST=your-unique-url.rds.amazonaws.com
DATABASE_PORT=5432
DATABASE_NAME=strapi
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=Password
AWS_ACCESS_KEY_ID=aws-access-key-id
AWS_ACCESS_SECRET=aws-access-secret
AWS_REGION=aws-region
AWS_BUCKET_NAME=my-project-bucket-name
We recommend you continue setting the NODE_ENV
variable in the ecosystem.config.js
file.
Use the following command to start pm2
:
cd ~
pm2 start ecosystem.config.js
Your Strapi project should now be available on http://your-ip-address:1337/
.
💡 TIP
Earlier, Port 1337
was allowed access for testing and setup purposes. After setting up NGINX, the Port 1337 needs to have access denied.
# 7. Configure PM2 Runtime to launch project on system startup.
Follow the steps below to have your app launch on system startup.
💡 TIP
These steps are based on the PM2 Runtime Startup Guide (opens new window).
- 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 /usr/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.
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-ubuntu
to verify everything is working.
# Create you first Administrator user
The next steps will create an Administrator user on the strapi AWS instance.
# 1. Locate your IPv4 Public IP
:
- Login as your regular user to your
EC2 Dashboard
- Click on
1 Running Instances
. - Below, in the Description tab, locate your IPv4 Public IP
# 2. Next, create your Administrator user, and login to Strapi:
- Go to
http://your-ip-address:1337/
- Complete the registration form.
- Click
Ready to Start
# 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 article provides additional information to the steps below: GitHub Creating Webhooks Guide (opens new window).
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.
(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
. The project uses the ecosystem.config.js
as the point of starting your application.)
var secret = 'your_secret_key'; // Your secret key from Settings in GitHub
var repo = '~/path-to-strapi-root-folder/'; // path to the root of your Strapi project on server
const http = require('http');
const crypto = require('crypto');
const exec = require('child_process').exec;
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
:- Within your AWS EC2 dashboard:
- In the left hand menu, click on
Security Groups
, - Select with the checkbox, the correct
Group Name
, e.g.strapi
, - At the bottom of the screen, in the Inbound tab, click
Edit
, and thenAdd Rule
:- Type:
Custom TCP
- Protocol:
TCP
- Port Range:
8080
- Source:
Custom
0.0.0.0/0, ::/0
- Type:
- Then
Save
- In the left hand menu, click on
- If the
ufw
firewall is enabled, configure settings to includeport 8080
by running the following command:
- Within your AWS EC2 dashboard:
sudo ufw allow 8080/tcp
Earlier you setup pm2
to start the services (your Strapi project) whenever the EC2 instance 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
cd ~
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:
sudo nano /etc/systemd/system/webhook.service
- In the
nano
editor, copy/paste the following script, but make sure to replaceubuntu
in two places if you changed the defaultubuntu
user, andpaste the $PATH
from above.
✋ CAUTION
Delete the #comments before saving, then save and exit.
[Unit]
Description=Github webhook
After=network.target
[Service]
Environment=PATH=/PASTE-PATH_HERE #path from echo $PATH (as above)
Type=simple
User=ubuntu #replace with your name, if changed from default ubuntu user
ExecStart=/usr/bin/nodejs /home/ubuntu/NodeWebHooks/webhook.js #replace with your name, if changed from default ubuntu user
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 (opens new window).
# 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 (opens new window) and configure it (opens new window).
💡 TIP
After setting up NGINX, for security purposes, you need to disable port access on
Port 1337
. You may do this easily from your EC2 Dashboard. InSecurity Groups
(lefthand menu), click the checkbox of the group, eg.strapi
, and below in theinbound
tab, clickEdit
, and delete the rule forPort Range
:1337
by click thex
.To install SSL, you will need to install and run Certbot by Let's Encrypt (opens new window).
Set-up Nginx with HTTP/2 Support (opens new window) for Ubuntu 18.04.
Your Strapi
project has been installed on an AWS EC2 instance using Ubuntu 18.04.