These integration guides are not official documentation and the Strapi Support Team will not provide assistance with them.
This is a step-by-step guide for deploying a Strapi project to Amazon AWS EC2 inside your AWS VPC. This guide will connect to an Amazon AWS RDS for managing and hosting the database. Optionally, this guide will show you how to connect host and serve images on Amazon AWS S3.
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. Your root user is therefore only used for a very few select tasks. 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.
searching for IAM
and clicking or going here: IAM Console.Click on Users
, in the left hand menu, and then click Add User
:
In the Set user details screen:
Programmatic access
and AWS Management Console access
.Autogenerate a password
or click Custom password
and provide one.uncheck
the Require password reset.Next: Permissions
.In the Set Permissions screen, do the following:
Create group
, name it, e.g. Developers
, and then choose appropriate policies under Policy Name:ec2
and check AmazonEC2FullAccess
RDS
and check AmazonRDSFullAccess
s3
and check AmazonS3FullAccess
vpc
and check AmazonVPCFullAccess
Create group
Add user to group
and check the Developers
group, to add the new user.Next: Tags
.Add tags (optional)
Next: Review
.Review
Previous
to correct anything.Create user
.Access key ID
and Secret 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.AWS Management Console Access sign-in link
. This will log you out of Administrator
.Log into
your AWS Management Console as your regular user
You may now proceed to the next steps.
A VPC is an isolated portion of the AWS Cloud populated by AWS objects, such as Amazon EC2 instances. A VPC is logically isolated from other virtual networks in the AWS Cloud. You can launch your AWS resources, such as Amazon EC2 instances, into your VPC. You can specify an IP address range for the VPC, add subnets, associate security groups, and configure route tables.
Find Services
, search for VPC
and click on EC2, Isolated Cloud Resources
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.
Create VPC
buttonSelect
VPC and More
Select
Auto-generate nametags. Add a suitable name, e.g. strapi-vpc
.Leave
IPv4 CIDR block as 10.0.0.0/16 (unless you have a specific reason to change it).Leave
Tenancy as Default.Select
2 for Number of Availability Zones (AZs)Select
2 for Number of Public SubnetsSelect
2 for Number of Private SubnetsSelect
0 for NAT gateways.
Select
S3 Gateway for VPC Endpoints.
Check
Enable DNS hostnames and Enable DNS resolution.Select
Create VPC.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.
Find Services
, search for ec2
and click on EC2, Virtual Servers in the Cloud
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.
Launch Instance
buttonSelect
Ubuntu Server 22.04 LTS (HVM), SSD Volume TypeEnsure General purpose
+ t2.small
is checked
.
Click the grey Next: Configure Instance Details
and Next: Add Storage
General Purpose SSD (gp2)
, then click Next: Add tags
.Next: Configure Security Group
.security settings
as follows:Create a new security group
strapi
strapi instance security settings
SSH
, Protocol: TCP
, Port Range 22
, Source: 0.0.0.0/0
(all IP addresses). If not, add it.Add rule
to add each of these rules:SSH
, Protocol: TCP
, Port Range 22
, Source: ::/0
HTTP
, Protocol: TCP
, Port Range 80
, Source: 0.0.0.0/0, ::/0
HTTPS
, Protocol: TCP
, Port Range 443
, Source: 0.0.0.0/0, ::/0
Type: Custom TCP Rule
, Protocol: TCP
, Port Range 1337
, 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.
Review and Launch
button.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:Create a new key pair
.ec2-strapi-key-pair
Launch Instances
button.Your instance is now running. Continue to the next steps.
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.
AWS RDS Service
In the top menu, click on Services
and do a search for rds
, click on RDS, Managed Relational Database Service
.
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)
.
Click the orange Create database
button.
Follow these steps to complete installation of a PostgreSQL
database:
PostgreSQL
, version PostgreSQL 10.x-R1Free Tier
.strapi-database
psql
database username and password.postgres
, or change (optional)Uncheck
Auto generate a password, and then type in a new secret password.Instace
dropdown, and select the EC2 instance you created earlier.strapi
.Create database
button.After a few minutes, you may refresh your page and see that your database has been successfully created.
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.
Amazon S3
In the top menu, click on Services
and do a search for s3
, click on Scalable storage in the cloud
.
Click on the blue Create bucket
button:
my-project-name-images
.EU (Paris)
or US East (N. Virgina)
.Next
.next
.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 policiesDo not grant Amazon S3 Log Delivery group write access to this bucket
.Next
.Create bucket
.You will set-up your EC2 server as a Node.js server. Including basic configuration and Git.
You will need your EC2 ip address:
AWS Console
, navigate to the AWS EC2
. In the top menu, click on Services
and do a search for ec2
, click on Virtual Servers in the cloud
.1 Running Instance
and note the IPv4 Public OP
address. E.g. 1.2.3.4
..pem
fileUser
.pem file. e.g. ec2-strapi-key-pair.pem
. This needs to be included in each attempt to SSH
into your EC2 server
. Move your .pem
file to ~/.ssh/
, follow these steps:downloads
~/.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
ubuntu
user:ssh -i ~/.ssh/ec2-strapi-key-pair.pem ubuntu@1.2.3.4
Welcome to Ubuntu 22.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-1.2.3.4:~$
The following steps will install Node.js (example using Node 20) onto your EC2 server.
cd ~
sudo apt-get update
...
sudo apt-get install -y ca-certificates curl gnupg
...
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
NODE_MAJOR=20
sudo apt-get update
...
sudo apt-get install nodejs -y
...
node -v && npm -v
The last command node -v && npm -v
should output two versions numbers, eg. v20.x.x, 6.x.x
.
The following steps are based on how to resolve access permissions from npmjs.com:
.npm-global
directory and set the path to this directory for node_modules
cd ~
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
~/.profile
file:sudo nano ~/.profile
Add these lines at the bottom of the ~/.profile
file.
1# set PATH so global node modules install without permission issues
2export PATH=~/.npm-global/bin:$PATH
source ~/.profile
You are now ready to continue to the next section.
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 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.
Git
is installedIf you see a git version 2.x.x
then you do have Git
installed. Check with the following command:
git --version
After installing and configuring Git on your EC2 instance. Please continue to the next step.
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.
pg
in your Strapi project.On your development machine, navigate to your Strapi project root directory:
Path: ./my-project/
npm install pg
./config/database.js
file.Copy/paste the following:
1module.exports = ({ env }) => ({
2 connection: {
3 client: "postgres",
4 connection: {
5 host: env("DATABASE_HOST", "127.0.0.1"),
6 port: env.int("DATABASE_PORT", 5432),
7 database: env("DATABASE_NAME", "strapi"),
8 user: env("DATABASE_USERNAME", ""),
9 password: env("DATABASE_PASSWORD", ""),
10 },
11 useNullAsDefault: true,
12 },
13});
1export default ({ env }) => ({
2 connection: {
3 client: "postgres",
4 connection: {
5 host: env("DATABASE_HOST", "127.0.0.1"),
6 port: env.int("DATABASE_PORT", 5432),
7 database: env("DATABASE_NAME", "strapi"),
8 user: env("DATABASE_USERNAME", ""),
9 password: env("DATABASE_PASSWORD", ""),
10 },
11 useNullAsDefault: true,
12 },
13});
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
.
1module.exports = ({ env }) => ({
2 upload: {
3 config: {
4 provider: 'aws-s3',
5 providerOptions: {
6 s3Options: {
7 accessKeyId: env('AWS_ACCESS_KEY_ID'),
8 secretAccessKey: env('AWS_ACCESS_SECRET'),
9 region: env('AWS_REGION'),
10 params: {
11 Bucket: env('AWS_BUCKET_NAME'),
12 },
13 }
14 },
15 // These parameters could solve issues with ACL public-read access — see [this issue](https://github.com/strapi/strapi/issues/5868) for details
16 actionOptions: {
17 upload: {
18 ACL: null
19 },
20 uploadStream: {
21 ACL: null
22 },
23 }
24 },
25 }
26});
1export default ({ env }) => ({
2 upload: {
3 config: {
4 provider: 'aws-s3',
5 providerOptions: {
6 s3Options: {
7 accessKeyId: env('AWS_ACCESS_KEY_ID'),
8 secretAccessKey: env('AWS_ACCESS_SECRET'),
9 region: env('AWS_REGION'),
10 params: {
11 Bucket: env('AWS_BUCKET_NAME'),
12 },
13 }
14 },
15 },
16 }
17});
See the documentation about using an upload provider here.
git add .
git commit -m 'Installed pg, aws-S3 upload provider and updated the config files'
git push
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. Make sure to uninstall the sqlite3 package if you changed your database to PostgresSQL.
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
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
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.
nano
editor and then copy/paste
the following:cd ~
pm2 init
sudo nano ecosystem.config.js
1module.exports = {
2 apps: [
3 {
4 name: 'your-app-name', // Your project name
5 cwd: '/home/ubuntu/my-project', // Path to your project
6 script: 'npm', // For this example we're using npm, could also be yarn
7 args: 'start', // Script to start the Strapi server, `start` by default
8 env: {
9 APP_KEYS: 'your app keys', // you can find it in your project .env file.
10 API_TOKEN_SALT: 'your api token salt',
11 ADMIN_JWT_SECRET: 'your admin jwt secret',
12 JWT_SECRET: 'your jwt secret',
13 NODE_ENV: 'production',
14 DATABASE_HOST: 'your-unique-url.rds.amazonaws.com', // database Endpoint under 'Connectivity & Security' tab
15 DATABASE_PORT: '5432',
16 DATABASE_NAME: 'strapi', // DB name under 'Configuration' tab
17 DATABASE_USERNAME: 'postgres', // default username
18 DATABASE_PASSWORD: 'Password',
19 AWS_ACCESS_KEY_ID: 'aws-access-key-id',
20 AWS_ACCESS_SECRET: 'aws-access-secret', // Find it in Amazon S3 Dashboard
21 AWS_REGION: 'aws-region',
22 AWS_BUCKET_NAME: 'my-project-bucket-name',
23 },
24 },
25 ],
26};
1export default {
2 apps: [
3 {
4 name: 'your-app-name',
5 cwd: '/home/ubuntu/my-project',
6 script: 'npm',
7 args: 'start',
8 env: {
9 NODE_ENV: 'production',
10 DATABASE_HOST: 'your-unique-url.rds.amazonaws.com', // database Endpoint under 'Connectivity & Security' tab
11 DATABASE_PORT: '5432',
12 DATABASE_NAME: 'strapi', // DB name under 'Configuration' tab
13 DATABASE_USERNAME: 'postgres', // default username
14 DATABASE_PASSWORD: 'Password',
15 AWS_ACCESS_KEY_ID: 'aws-access-key-id',
16 AWS_ACCESS_SECRET: 'aws-access-secret', // Find it in Amazon S3 Dashboard
17 AWS_REGION: 'aws-region',
18 AWS_BUCKET_NAME: 'my-project-bucket-name',
19 },
20 },
21 ],
22};
You can also set your environment variables in a .env
file in your project like so:
1DATABASE_HOST=your-unique-url.rds.amazonaws.com
2DATABASE_PORT=5432
3DATABASE_NAME=strapi
4DATABASE_USERNAME=postgres
5DATABASE_PASSWORD=Password
6AWS_ACCESS_KEY_ID=aws-access-key-id
7AWS_ACCESS_SECRET=aws-access-secret
8AWS_REGION=aws-region
9AWS_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/
. Your IP address will be the one corresponding to your Ubuntu server.
Follow the steps below to have your app launch on system startup.
$ 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
$ 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
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
sudo reboot
command. You will need to login again with your non-root user and then run pm2 list
and systemctl status pm2-ubuntu
to verify everything is working.The next steps will create an Administrator user on the strapi AWS instance.
IPv4 Public IP
EC2 Dashboard
1 Running Instances
.http://your-ip-address:1337/admin
Ready to Start
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.
You need to access the Settings
tab for your Strapi Project Repository
:
Settings
for your repository.Webhooks
, then click Add Webhook
.http://your-ip-address:8080
application/json
Just the push event
YourSecret
Add Webhook
.Next, you need to create a Webhook Script
on your server. These commands create a new file called webhook.js
which will hold two variables:
cd ~
mkdir NodeWebHooks
cd NodeWebHooks
sudo nano webhook.js
nano
editor, copy/paste the following script, but make sure to replace your_secret_key
and repo
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.)
1var secret = 'your_secret_key'; // Your secret key from Settings in GitHub
2var repo = '~/path-to-strapi-root-folder/'; // path to the root of your Strapi project on server
3
4const http = require('http');
5const crypto = require('crypto');
6const exec = require('child_process').exec;
7
8const PM2_CMD = 'cd ~ && pm2 startOrRestart ecosystem.config.js';
9
10http
11 .createServer(function(req, res) {
12 req.on('data', function(chunk) {
13 let sig =
14 'sha1=' +
15 crypto
16 .createHmac('sha1', secret)
17 .update(chunk.toString())
18 .digest('hex');
19
20 if (req.headers['x-hub-signature'] == sig) {
21exec(`cd ${repo} && git pull && NODE_ENV=production npm run build && ${PM2_CMD}`, (error, stdout, stderr) => {
22 if (error) {
23 console.error(`exec error: ${error}`);
24 return;
25 }
26 console.log(`stdout: ${stdout}`);
27 console.log(`stderr: ${stderr}`);
28 });
29 }
30 });
31
32 res.end();
33 })
34 .listen(8080);
port 8080
:Security Groups
,Group Name
, e.g. strapi
,Edit
, and then Add Rule
:Custom TCP
TCP
8080
Custom
0.0.0.0/0, ::/0
Save
ufw
firewall is enabled, configure settings to include port 8080
by running the following command: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
echo $PATH
and copy the output for use in the next step.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
webhook.service
file:sudo nano /etc/systemd/system/webhook.service
nano
editor, copy/paste the following script, but make sure to replace ubuntu
in two places if you changed the default ubuntu
user, and paste the $PATH
from above.[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/node /home/ubuntu/NodeWebHooks/webhook.js #replace with your name, if changed from default ubuntu user
Restart=on-failure
[Install]
WantedBy=multi-user.target
sudo systemctl enable webhook.service
sudo systemctl start webhook
sudo systemctl status webhook
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 22.04.
Your Strapi project has been installed on an AWS EC2 instance using Ubuntu 22.04.