Deploying Strapi Head

Configuration

Now that all components are installed, it's time to configure them to work together with Strapi.

1. Creating a PostgreSQL Database for Strapi

First, let's create a user and a database in PostgreSQL that Strapi will connect to.

# Connect to PostgreSQL as the postgres user
sudo -i -u postgres psql

Inside the PostgreSQL console, execute the following commands:

CREATE USER strapiuser WITH PASSWORD 'your_very_strong_password';
CREATE DATABASE strapidb WITH OWNER strapiuser;
GRANT ALL PRIVILEGES ON DATABASE strapidb TO strapiuser;
\q

Replace ваш_очень_сложный_пароль with a strong password. Exit the PostgreSQL console (\q).

2. Creating a Strapi Project

Navigate to your user's home directory (/home/strapiuser) or another convenient directory, such as /var/www. We will use /var/www for web applications.

sudo mkdir -p /var/www/strapi
sudo chown -R strapiuser:strapiuser /var/www/strapi
cd /var/www/strapi

Create a new Strapi project. We use the --no-run flag so it doesn't start immediately.

npx create-strapi-app@latest my-strapi-project --quickstart --no-run

During installation, you will be prompted to choose the installation type. For this guide, select Custom (manual settings), then PostgreSQL as the database. Enter the database connection details you created earlier (Host: 127.0.0.1, Port: 5432, Database: strapidb, Username: strapiuser, Password: ваш_очень_сложный_пароль).

Navigate to the project directory:

cd my-strapi-project

3. Configuring Strapi Environment Variables

Secrets and configuration parameters are best stored in a .env file. Create or edit the .env file in the root directory of your Strapi project.

nano .env

Add or update the following lines:

HOST=0.0.0.0
PORT=1337
APP_KEYS=your_very_strong_and_long_application_key # Automatically generated with --quickstart, but it's better to regenerate
API_TOKEN_SALT=your_very_strong_and_long_api_token_key
ADMIN_JWT_SECRET=your_very_strong_and_long_admin_panel_key
JWT_SECRET=your_very_strong_and_long_jwt_key

DATABASE_CLIENT=pg
DATABASE_HOST=127.0.0.1
DATABASE_PORT=5432
DATABASE_NAME=strapidb
DATABASE_USERNAME=strapiuser
DATABASE_PASSWORD=your_very_strong_password
DATABASE_SSL=false

NODE_ENV=production

To generate strong random keys for APP_KEYS, API_TOKEN_SALT, ADMIN_JWT_SECRET, JWT_SECRET, you can use the command:

node -e "console.log(crypto.randomBytes(32).toString('hex'))"

Execute it several times to get unique keys for each parameter. Save the file.

4. Running Strapi with PM2

Now let's run Strapi in production mode using PM2.

# Ensure you are in the root directory of your Strapi project (/var/www/strapi/my-strapi-project)
npm run build
pm2 start npm --name "strapi-app" -- run start
# Save PM2 process list for autostart
pm2 save

Check Strapi status:

pm2 list
pm2 logs strapi-app

Strapi should be running and listening on port 1337 (default).

5. Configuring Nginx as a Reverse Proxy

Let's create an Nginx configuration file for your domain (e.g., api.yourdomain.com).

sudo nano /etc/nginx/sites-available/api.yourdomain.com

Insert the following configuration, replacing api.yourdomain.com with your domain:

server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:1337;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;
    }
}

Save the file. Create a symbolic link to this file in sites-enabled and check the Nginx syntax:

sudo ln -s /etc/nginx/sites-available/api.yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t

If the syntax is okay (syntax is ok), reload Nginx:

sudo systemctl restart nginx

At this point, your Strapi should be accessible via HTTP through Nginx at http://api.yourdomain.com (ensure that the DNS record for your domain points to your VPS's IP).

6. Configuring SSL with Certbot (Let's Encrypt)

To ensure security and trust, you need to configure HTTPS. Certbot will automatically obtain and install SSL certificates from Let's Encrypt.

# Install Certbot and Nginx plugin
sudo apt install -y certbot python3-certbot-nginx
# Obtain and install certificate
sudo certbot --nginx -d api.yourdomain.com

Certbot will ask you a few questions: an email address for notifications, agreement to the terms of service, and possibly offer to redirect HTTP traffic to HTTPS (choose "2: Redirect"). Certbot will automatically update the Nginx configuration, adding SSL parameters.

Check that Certbot has configured automatic certificate renewal:

sudo systemctl status certbot.timer

The timer should be active. If not, enable it: sudo systemctl enable certbot.timer. Now your Strapi is accessible via HTTPS: https://api.yourdomain.com.

7. Verifying Functionality

Open your domain (e.g., https://api.yourdomain.com) in a browser. You should see the Strapi welcome page or the admin panel login page. If this is the first launch, you will be prompted to create the first administrator.

You can also check API accessibility via curl:

curl -I https://api.yourdomain.com/admin/

You should see HTTP headers with a status code of 200 OK or 302 Found (redirection to the login page).

Backups and Maintenance

Regular backups and timely maintenance are key to the long-term stability and security of your Strapi project.

What to back up

For a full Strapi recovery, you will need to back up several types of data:

• PostgreSQL Database: Contains all your content, collection structure, and users. This is the most important component.
• Strapi Project Files: Include configuration files (especially .env), plugins, custom controllers, and services. Although most data is in the DB, application settings are also important.
• Media Files: Images, videos, and other files uploaded via Strapi. By default, they are stored in ./public/uploads within the project, unless external storage (S3) is configured.

Simple auto-backup script

Let's create a simple script for backing up the database and files, which will run on a schedule via cron.

Create a directory for backups (e.g., /var/backups/strapi):

sudo mkdir -p /var/backups/strapi
sudo chown -R strapiuser:strapiuser /var/backups/strapi

Create the script file backup_strapi.sh in the home directory of the strapiuser user:

nano /home/strapiuser/backup_strapi.sh

Insert the following content:

#!/bin/bash

# --- Configuration ---
BACKUP_DIR="/var/backups/strapi"
DATE=$(date +%Y%m%d_%H%M%S)
DB_NAME="strapidb"
DB_USER="strapiuser"
STRAPI_PROJECT_PATH="/var/www/strapi/my-strapi-project"
RETENTION_DAYS=7 # How many days to keep backups

# --- Create backup directory for current date ---
CURRENT_BACKUP_DIR="$BACKUP_DIR/$DATE"
mkdir -p "$CURRENT_BACKUP_DIR"

# --- PostgreSQL Backup ---
echo "Dumping PostgreSQL database '$DB_NAME'..."
PGPASSWORD='ваш_очень_сложный_пароль' pg_dump -U "$DB_USER" -h localhost "$DB_NAME" > "$CURRENT_BACKUP_DIR/$DB_NAME.sql"
if [ $? -eq 0 ]; then
    echo "PostgreSQL dump successful."
else
    echo "Error dumping PostgreSQL database!"
    exit 1
fi

# --- Backup Strapi project files and media files ---
echo "Archiving Strapi project files..."
tar -czf "$CURRENT_BACKUP_DIR/strapi_project.tar.gz" -C "$(dirname "$STRAPI_PROJECT_PATH")" "$(basename "$STRAPI_PROJECT_PATH")"
if [ $? -eq 0 ]; then
    echo "Strapi project files archived successful."
else
    echo "Error archiving Strapi project files!"
    exit 1
fi

# --- Delete old backups ---
echo "Cleaning up old backups (older than $RETENTION_DAYS days)..."
find "$BACKUP_DIR" -maxdepth 1 -type d -mtime +"$RETENTION_DAYS" -exec rm -rf {} \;
echo "Cleanup complete."

echo "Backup finished at $DATE"

Replace ваш_очень_сложный_пароль with your PostgreSQL user password. Make the script executable:

chmod +x /home/strapiuser/backup_strapi.sh

Add the script to cron for daily execution (e.g., at 3:00 AM).

crontab -e

Add the following line to the end of the file to make the script run every day at 03:00:

0 3 * * * /home/strapiuser/backup_strapi.sh >> /var/log/strapi_backup.log 2>&1

This command will redirect the script's output to the /var/log/strapi_backup.log file, which will help track its execution.

Where to store backups

It is extremely important to store backups OUTSIDE the main server. If the server fails, you will lose both your data and your backups. Recommended options:

• External S3-compatible object storage: For example, Amazon S3, DigitalOcean Spaces, Backblaze B2. This is cost-effective and reliable. You can use utilities like s3cmd or rclone to automatically synchronize the backup directory with S3.
• Separate VPS: An inexpensive VPS in a different location, used exclusively for backup storage. Can be synchronized via rsync or sftp.
• Local storage on your computer: For very small projects, but this is not automated or scalable.

Updates: rolling vs maintenance window

Updating software on a production server requires caution.

• OS and base package updates (apt upgrade): It is recommended to perform these regularly (once a month), but always within a "maintenance window" when the load is minimal. Before updating, make a full backup. After updating, especially if the kernel was updated, a reboot is required.
• Strapi updates: Strapi updates (especially between major versions, e.g., v4 to v5) may require database and code migrations. Always test updates on a staging server before applying them to production. Perform within a maintenance window.
• Node.js updates: Node.js updates can also affect Strapi. Check version compatibility.

Always make a backup before any major update!

Troubleshooting + FAQ

This section contains answers to frequently asked questions and solutions to common problems you may encounter when deploying Strapi.

Nginx returns 502 Bad Gateway error

What to check: A 502 error usually means that Nginx cannot connect to the backend service (Strapi in our case). Make sure Strapi is running and listening on the correct port (default 1337). Check Nginx logs (sudo tail -f /var/log/nginx/error.log) and Strapi logs (pm2 logs strapi-app).

How to fix: Make sure the PM2 Strapi process is active (pm2 list). If not, try running it manually (cd /var/www/strapi/my-strapi-project && npm run start) and check for errors. Verify that proxy_pass http://localhost:1337; in the Nginx configuration points to the correct port.

Strapi does not start, database connection errors

What to check: Check the .env file in the root of your Strapi project. Make sure the DATABASE_HOST, DATABASE_PORT, DATABASE_NAME, DATABASE_USERNAME, and DATABASE_PASSWORD parameters are correct. Verify that PostgreSQL is running (sudo systemctl status postgresql) and that the strapiuser user has access rights to the strapidb database.

How to fix: Reset the PostgreSQL user password (sudo -i -u postgres psql -c "ALTER USER strapiuser WITH PASSWORD 'новый_пароль';") and update it in .env. Make sure the local host 127.0.0.1 is allowed for connection in the /etc/postgresql/16/main/pg_hba.conf file (there should be a line host all all 127.0.0.1/32 md5 or scram-sha-256). After making changes to pg_hba.conf, restart PostgreSQL: sudo systemctl restart postgresql.

Cannot obtain SSL certificate with Certbot

What to check: Make sure your domain (e.g., api.yourdomain.com) correctly points to your VPS IP address via an A-record in DNS. Certbot must be able to connect to your server on port 80 (HTTP) to verify domain ownership. Check that Nginx is running and correctly listening on port 80.

How to fix: Temporarily disable UFW (sudo ufw disable) and try again. If this helped, then the firewall is blocking ports. Make sure sudo ufw allow http and sudo ufw allow https are enabled. Check your Nginx configuration for errors (sudo nginx -t). Make sure no other processes are occupying port 80 or 443.

What is the minimum suitable VPS configuration?

For a minimal Strapi deployment for a small project or testing, you can start with a VPS with 2 CPU cores, 4 GB RAM, and 80 GB SSD. This will be sufficient for the operating system, PostgreSQL, and Strapi itself without heavy load. However, if you plan active use, a large amount of content, or many users, it is recommended to increase RAM to 8 GB and possibly consider more performant disks.

What to choose — VPS or dedicated for this task?

For most Strapi projects, especially in the initial and medium stages of development, a VPS is the optimal choice. It offers an excellent balance between performance, flexibility, and cost. A dedicated server becomes justified only under very high loads (thousands of concurrent users, intensive DB operations), the need for maximum resource isolation, specific hardware requirements, or special regulatory norms. Start with a VPS and scale to dedicated if and when your needs exceed virtualization capabilities.

Slow Strapi admin panel performance

What to check: Slow admin panel performance can be caused by insufficient VPS resources (CPU or RAM), a slow database, or unoptimized queries. Check server resource usage (htop or free -h).

How to fix: Increase the amount of RAM on the VPS if it is close to exhaustion. Optimize database queries if you have very complex content structures. Make sure the database is on an SSD. For a production environment, always run Strapi in NODE_ENV=production mode, as it consumes more resources in development mode.

Conclusions and Next Steps

Congratulations! You have successfully deployed Strapi Headless CMS on your VPS, configuring PostgreSQL, Nginx, and SSL certificates. You now have a powerful, secure, and flexible content management platform, ready for integration with any frontend application.

Here are some next steps you can take to further develop your Strapi project:

• Frontend Development: Use your Strapi API to create websites (with React, Vue, Next.js, Nuxt.js), mobile applications, or other digital products.
• Extending Strapi Functionality: Explore the Strapi documentation to create custom fields, plugins, lifecycles, and user roles.
• Monitoring and Optimization: Implement monitoring tools (e.g., Prometheus + Grafana) to track server and Strapi performance, to promptly respond to potential issues and optimize resources.