translation Documentation

1. Project Overview & Quickstart (evershopcommerce/translation) Copy Chapter

Technical Documentation: evershopcommerce/translation

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

translation

Agent Skills & Rules Copy Section

• Discovered 21 agent rule(s) and prompt configurations.

--- METRICS ---

• Files Extracted: 1
• Estimated Token Budget: ~25 tokens
• Canonical Reference: https://codewiki.google/github.com/evershopcommerce/translation

2. Official Technical Reference & Guides (evershopcommerce/docs) Copy Chapter

File: docs/development/deployment/deploy-evershop-to-aws.md Copy Chapter

sidebar_position: 10
keywords:

• AWS deployment
• EC2 hosting
• RDS PostgreSQL
• Node.js production deployment
  sidebar_label: Deploy to AWS
  title: Deploy EverShop to AWS

Deploy EverShop to AWS

This comprehensive guide walks you through the process of deploying EverShop to Amazon Web Services (AWS) using EC2 for application hosting and RDS for PostgreSQL database management. This approach provides a scalable, reliable production environment for your ecommerce platform.

:::tip
Before you go live, run down the Production Checklist — it lists every environment variable EverShop reads at boot, the built-in per-IP rate limits, and what the build and start sequence actually does.
:::

Prerequisites Copy Chapter

Before beginning, ensure you have:

• An active AWS account (this guide uses free tier resources where possible)
• Basic familiarity with AWS console navigation
• SSH client for connecting to your EC2 instance

EC2 Instance Setup Copy Chapter

Creating an EC2 Instance Copy Section

First, we need to provision a virtual server to host the EverShop application:

:::info
If you're new to AWS, follow the official EC2 getting started guide for detailed instructions on creating your first instance.
:::

For optimal compatibility with EverShop, we recommend:

• Operating System: Ubuntu 20.04 LTS
• Instance Type: t2.micro for testing (free tier eligible) or t3.small/medium for production use
• Storage: At least 20GB of EBS storage
• Security Group: Configure to allow HTTP (port 80), HTTPS (port 443), and SSH (port 22)

Installing Required Software Copy Section

After creating and connecting to your EC2 instance via SSH, install the necessary software components:

1. Install Node.js and NPM

EverShop requires Node.js version 20.9 or higher and NPM version 9.x or higher:

sudo apt update
sudo apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Verify the installation:

node -v  # Should show v20.x.x or higher
npm -v   # Should show 9.x.x or higher

2. Install PM2 Process Manager

PM2 will ensure your EverShop application runs continuously and restarts automatically if the server reboots:

sudo npm install -g pm2

Verify the installation:

pm2 -v

Configure PM2 to start automatically on server boot:

pm2 startup systemd

Follow any additional instructions provided by the command.

3. Install and Configure Nginx

Nginx will act as a reverse proxy, directing traffic to your Node.js application:

sudo apt install -y nginx

Create a configuration file for your EverShop application:

sudo nano /etc/nginx/sites-available/evershop.conf

Add the following configuration, replacing yourdomain.com with your actual domain name (or use the EC2 public DNS temporarily):

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

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

    # Handle large file uploads
    client_max_body_size 50M;
}

Enable the configuration and disable the default site:

sudo ln -s /etc/nginx/sites-available/evershop.conf /etc/nginx/sites-enabled/
sudo unlink /etc/nginx/sites-enabled/default

Test the configuration and restart Nginx:

sudo nginx -t
sudo systemctl restart nginx

Database Setup Copy Chapter

Creating an RDS PostgreSQL Instance Copy Section

EverShop requires PostgreSQL 13 or higher. Let's create a managed database instance:

:::info
For detailed instructions on creating an RDS instance, refer to the AWS RDS documentation.
:::

1. Navigate to the RDS dashboard in the AWS console
2. Click "Create database"
3. Select "Standard create" and choose PostgreSQL
4. Select version 13 or higher
5. Choose the appropriate instance size (db.t3.micro is free tier eligible)
6. Configure storage, connectivity, and security settings
7. Set your master username and password
8. Complete the creation process

Configuring Security Groups Copy Section

For your EC2 instance to access the RDS database:

1. Identify the security group of your RDS instance
2. Edit its inbound rules to allow PostgreSQL traffic (port 5432) from your EC2 instance's security group or IP address

:::info
For detailed instructions on configuring security groups, see the AWS RDS VPC documentation.
:::

Creating the Database and User Copy Section

Connect to your RDS instance using a PostgreSQL client like pgAdmin or psql:

psql -h your-rds-endpoint.rds.amazonaws.com -U master_username -d postgres

Create a dedicated database and user for EverShop:

CREATE DATABASE evershop;
CREATE USER evershop WITH ENCRYPTED PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE evershop TO evershop;

Source Code Deployment Copy Chapter

Setting Up Your Repository Copy Section

For streamlined deployment:

1. Fork the EverShop project template to your GitHub account
2. Add any custom themes or extensions to your forked repository

Creating a Deployment Script Copy Section

Create a deployment script on your EC2 instance to automate the process:

sudo mkdir -p /var/www/evershop
cd /var/www/evershop
sudo nano deploy.sh

Add the following script, replacing the placeholder values with your actual GitHub information:

#!/bin/bash

# GitHub authentication and repository details
TOKEN="your_github_personal_access_token"
REPO_OWNER="your_github_username"
REPO_NAME="your_repository_name"
BRANCH="main"

# Check if tar is installed
echo "Checking if tar is installed..."
if ! command -v tar &> /dev/null
then
    echo "tar is not installed, installing now..."
    sudo apt-get install tar -y
fi

# Set deployment directories
CURRENT_BUILD="current"
TIMESTAMP=$(date +"%Y-%m-%d_%H-%M-%S")
NEW_BUILD="build_$TIMESTAMP"

# Download source from GitHub
echo "Downloading source from GitHub..."
wget --header="Authorization: token $TOKEN" -O $NEW_BUILD.tar.gz https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/tarball/${BRANCH}

# Extract source code
echo "Extracting source to $NEW_BUILD..."
mkdir $NEW_BUILD
tar -xf $NEW_BUILD.tar.gz -C $NEW_BUILD --strip-components 1
rm $NEW_BUILD.tar.gz

# Carry the runtime configuration into the new build BEFORE building.
# `evershop build` reads the .env file, so it has to be in place first.
if [ -f "$CURRENT_BUILD/.env" ]; then
  echo "Copying .env into the new build..."
  cp $CURRENT_BUILD/.env $NEW_BUILD/
fi

if [ -d "$CURRENT_BUILD/config" ]; then
  cp -R $CURRENT_BUILD/config $NEW_BUILD/
fi

# Install dependencies
echo "Installing npm dependencies..."
cd $NEW_BUILD && npm install --production

# Build the application
echo "Building the application..."
npm run build
cd ..

# Backup current build
if [ -d "$CURRENT_BUILD" ]; then
  echo "Backing up current build..."
  if [ -d "previous-build" ]; then
    rm -rf previous-build
  fi
  mv $CURRENT_BUILD previous-build
fi

# Deploy new build
echo "Deploying new build..."
mv $NEW_BUILD $CURRENT_BUILD

# Copy uploaded media forward from the previous build
if [ -d "previous-build" ]; then
  echo "Copying media files..."
  if [ -d "previous-build/media" ]; then
    cp -R previous-build/media $CURRENT_BUILD/
  else
    mkdir -p $CURRENT_BUILD/media
  fi
fi

# Set permissions
echo "Setting permissions..."
chmod -R 755 $CURRENT_BUILD
chmod -R 777 $CURRENT_BUILD/media

# Re-restrict the environment file — the recursive chmod above widened it.
if [ -f "$CURRENT_BUILD/.env" ]; then
  chmod 600 $CURRENT_BUILD/.env
fi

# Restart application with PM2
echo "Restarting application..."
cd $CURRENT_BUILD
pm2 stop evershop 2>/dev/null || true
pm2 start npm --name "evershop" -- start

echo "Deployment completed successfully!"

Make the script executable:

sudo chmod +x deploy.sh

Creating Your Environment File Copy Section

EverShop reads its database credentials from environment variables, loaded from a .env file in the project root. This is the same file the evershop install setup wizard writes on a local install — on a server you create it by hand.

Create it in the directory the deployment script treats as the live build:

sudo mkdir -p /var/www/evershop/current
sudo nano /var/www/evershop/current/.env

Add your database connection and the production settings:

DB_HOST="your-rds-endpoint.rds.amazonaws.com"
DB_PORT="5432"
DB_NAME="evershop"
DB_USER="evershop"
DB_PASSWORD="secure_password"
DB_SSLMODE="require"

PORT="3000"

EVERSHOP_HOME_URL="https://yourdomain.com"
TRUST_PROXY_HOPS="1"

Lock the file down — it holds your database password:

sudo chmod 600 /var/www/evershop/current/.env

:::info
RDS instances present a certificate signed by the Amazon RDS CA. Use DB_SSLMODE="require" for an encrypted connection. If you want full certificate verification, download the RDS root certificate bundle and point DB_SSLROOTCERT at it; use DB_SSLMODE="no-verify" only as a temporary fallback.
:::

:::caution
The config/<env>.json files are still read, but the database connection is not configured there. Putting a system.database block in config/default.json has no effect — EverShop reads DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD and DB_SSLMODE from the environment. Use config/ for non-secret deployment settings such as the active theme and extension wiring.
:::

Setting the Public Base URL Copy Section

EVERSHOP_HOME_URL overrides the shop.homeUrl configuration key and is the recommended way to set your production base URL.

EVERSHOP_HOME_URL="https://yourdomain.com"

Everything EverShop emits as an absolute URL depends on it: links in transactional emails, canonical tags, hreflang alternates, and the <loc> entries plus the Sitemap: line in robots.txt. If it is left unset, EverShop falls back to shop.homeUrl and then to http://localhost: — which means customer emails go out pointing at localhost.

:::danger A malformed value stops the server from booting
EVERSHOP_HOME_URL is validated during startup. It must be an absolute http or https URL. A value like yourdomain.com (no scheme), or one using another protocol, throws during bootstrap and the process exits before it listens — PM2 will show the app repeatedly restarting.

Set the full origin with a scheme and no trailing path. Leaving the variable unset is fine; setting it to something invalid is fatal.
:::

:::tip
Set it to your HTTPS domain once Certbot has issued your certificate (see Securing Your Deployment below). If you set it to http:// and later switch to HTTPS, remember to update it — otherwise emails keep linking to the insecure URL.
:::

Setting the Proxy Hop Count Copy Section

Nginx sits in front of the Node process and forwards the client address in X-Forwarded-For (that is what the proxy_set_header X-Forwarded-For line in the Nginx config above does). TRUST_PROXY_HOPS tells EverShop how many of those proxies to trust. It drives Express's trust proxy setting, which determines request.ip — and request.ip is what the built-in rate limiter buckets on.

An unset, empty or non-numeric value falls back to 1. Count the hops that actually terminate and re-forward the connection, and set the variable to that number. If you put an ALB or CloudFront in front of this instance, raise the value to 2.

Running the Deployment Copy Section

Execute the deployment script:

cd /var/www/evershop
sudo ./deploy.sh

After deployment completes, your EverShop application should be running. You can access it using your EC2 instance's public DNS or your custom domain (if configured).

The admin panel is available at https://yourdomain.com/admin or http://your-ec2-public-dns/admin.

Securing Your Deployment Copy Chapter

Installing SSL Certificate with Let's Encrypt Copy Section

For production environments, secure your site with HTTPS:

1. Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

2. Obtain and install a certificate:

sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

3. Follow the interactive prompts to complete the process.

Certbot will automatically modify your Nginx configuration to redirect HTTP traffic to HTTPS.

Setting Up Automatic Certificate Renewal Copy Section

Let's Encrypt certificates expire after 90 days. Set up automatic renewal:

sudo systemctl status certbot.timer

This command should show that the automatic renewal service is active.

Maintenance and Monitoring Copy Chapter

Setting Up Log Rotation Copy Section

Configure log rotation to manage your application logs:

sudo nano /etc/logrotate.d/pm2

Add the following configuration:

/var/www/evershop/.pm2/logs/*.log {
  daily
  rotate 7
  compress
  delaycompress
  missingok
  notifempty
  create 0640 ubuntu ubuntu
}

Monitoring Your Application Copy Section

Use PM2 to monitor your application:

pm2 monit

For more advanced monitoring, consider integrating with AWS CloudWatch.

Conclusion Copy Chapter

You've successfully deployed EverShop to AWS using EC2 for hosting the application and RDS for managing the PostgreSQL database. This setup provides a robust, scalable foundation for your ecommerce platform.

For production environments, consider implementing additional best practices:

• Setting up automatic backups for your RDS instance
• Implementing AWS CloudWatch for comprehensive monitoring
• Configuring a CDN like CloudFront for improved content delivery
• Setting up an auto-scaling group for handling variable traffic loads

By following this guide, you've created a deployment that balances performance, security, and maintainability for your EverShop store.

File: docs/development/deployment/deploy-evershop-to-azure.md Copy Chapter

sidebar_position: 5
keywords:

• Azure deployment
• EverShop cloud hosting
• Microsoft Azure App Service
• Node.js deployment
  sidebar_label: Deploy to Azure
  title: Deploy EverShop to Microsoft Azure

Deploy EverShop to Microsoft Azure

This comprehensive guide walks you through the process of deploying your EverShop ecommerce platform to Microsoft Azure using Azure App Service and Azure Database for PostgreSQL.

:::tip
Before you go live, run down the Production Checklist — it lists every environment variable EverShop reads at boot, the built-in per-IP rate limits, and what the build and start sequence actually does.
:::

Prerequisites Copy Chapter

Before beginning the deployment process, ensure you have:

1. An active Microsoft Azure account with subscription access
2. An EverShop project installed and running on your local machine
3. Git installed on your local machine (for version control and deployment)

Step 1: Create a New Azure Web App Copy Chapter

1. Log in to the Azure portal at https://portal.azure.com.

2. Click the "+ Create a resource" button in the Azure portal dashboard.

3. Search for "Web App & Database" and select it from the search results.

4. Click the "Create" button to begin configuring your web application.

5. Configure your web application with the following settings:

6. Configure your database with appropriate settings for your EverShop deployment:

7. Click "Review + create" and then "Create" to provision your web application and database. Once completed, you'll see your resources in the Azure portal:

Step 2: Configure Deployment Options Copy Chapter

Azure supports multiple deployment methods. For this guide, we'll use the local Git deployment approach:

1. Navigate to your newly created web app in the Azure portal.

2. In the left menu, select "Deployment Center."

3. Choose Local Git as your deployment option.

4. Click the "Save" button to confirm your deployment configuration.

Step 3: Add Git Remote to Your Local Project Copy Chapter

After configuring the deployment options, Azure will generate a Git URL for your repository:

Add this Git remote to your local EverShop project:

git remote add azure <your-git-url>

:::caution
If your local project is not already a Git repository, initialize one first by running:

git init

Then add and commit your files before proceeding to the next step:

git add .
git commit -m "Initial commit for Azure deployment"

:::

Step 4: Configure Your Local Project Copy Chapter

Configure NPM Scripts Copy Section

Azure's deployment process automatically runs npm install followed by npm run build. Ensure your package.json file includes these scripts:

{
  "name": "evershop",
  "version": "1.0.0",
  "description": "",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "build": "evershop build",
    "start": "evershop start",
    "user:create": "evershop user:create",
    "user:changePassword": "evershop user:changePassword"
  },
  "workspaces": ["extensions/*"],
  "author": "EverShop",
  "license": "ISC",
  "dependencies": {
    "@evershop/evershop": "latest"
  }
}

:::info
evershop build takes no flags. Asset minification is always on in a production build and cannot be turned off.
:::

Add PM2 Configuration File Copy Section

Azure App Service uses PM2 as its Node.js process manager. Create a PM2 configuration file in your project root:

module.exports = {
  apps: [
    {
      name: "evershopAzure",
      script: "npm",
      env: {
        NODE_ENV: "production",
      },
      args: "run start",
    },
  ],
};

Create a .gitignore File Copy Section

Your local project structure should look similar to this:

├── .evershop
├── .log
├── extensions
├── media
├── themes
├── node_modules
├── public
├── .env
├── ecosystem.config.cjs
├── package.json
├── package-lock.json
└── README.md

Create a .gitignore file to exclude unnecessary files from deployment:

.evershop
.log
node_modules
.env

Step 5: Configure Environment Variables Copy Chapter

EverShop requires specific environment variables for database connectivity. Configure these in the Azure portal:

1. Go to your web app in the Azure portal and navigate to the "Configuration" section.

2. Rename the following default Azure PostgreSQL environment variables to match EverShop's expected names:

   • AZURE_POSTGRESQL_DBNAME → DB_NAME
   • AZURE_POSTGRESQL_USERNAME → DB_USER
   • AZURE_POSTGRESQL_PASSWORD → DB_PASSWORD
   • AZURE_POSTGRESQL_HOST → DB_HOST
   • AZURE_POSTGRESQL_PORT → DB_PORT

3. Add these additional required environment variables:

   • DB_SSLMODE: Set to require to enable SSL connections to the database
   • PORT: Set to 3000 to specify the port EverShop will use
   • EVERSHOP_HOME_URL: Your store's public base URL, e.g. https://your-app.azurewebsites.net (or your custom domain once mapped)
   • TRUST_PROXY_HOPS: Set to 1 — App Service terminates TLS at its own front end and forwards to your container

Set the public base URL Copy Section

EVERSHOP_HOME_URL overrides the shop.homeUrl configuration key and is the recommended way to set your production base URL — no config file needs to be edited or redeployed to change it.

EVERSHOP_HOME_URL=https://your-app.azurewebsites.net

Everything EverShop emits as an absolute URL depends on it: links in transactional emails, canonical tags, hreflang alternates, and the <loc> entries plus the Sitemap: line in robots.txt. If it is left unset, EverShop falls back to shop.homeUrl and then to http://localhost: — which means customer emails go out pointing at localhost.

:::danger A malformed value stops the server from booting
EVERSHOP_HOME_URL is validated during startup. It must be an absolute http or https URL. A value like your-app.azurewebsites.net (no scheme), or one using another protocol, throws during bootstrap and the process exits before it listens.

Set the full origin with a scheme and no trailing path. Leaving the variable unset is fine; setting it to something invalid is fatal.
:::

Set the proxy hop count Copy Section

TRUST_PROXY_HOPS tells EverShop how many reverse proxies sit in front of the app. It drives Express's trust proxy setting, which determines request.ip — and request.ip is what the built-in rate limiter buckets on.

An unset, empty or non-numeric value falls back to 1. Count the hops that actually terminate and re-forward the connection, and set the variable to that number.

4. Save your configuration changes.

Step 6: Deploy Your Project Copy Chapter

With configuration complete, deploy your EverShop application to Azure:

git push azure master

:::caution
During your first deployment, Azure will prompt you for Git credentials. You can find these in the "Deployment Center" section of your web app:

:::

The initial deployment may take several minutes. Once completed, your site will be accessible at the URL provided by Azure:

Step 7: Create an Administrator Account Copy Chapter

After deploying your EverShop store, create an administrator account:

1. Connect to your web app using the SSH feature in the Azure portal.

2. Navigate to your application directory:

cd /home/site/wwwroot

3. Create an admin user:

npm run user:create -- --email "[email protected]" --password "securePassword" --name "Admin Name"

4. Access your admin panel at https://<your-azure-domain>/admin and log in using the credentials you just created.

Step 8: Configure Custom Domain (Optional) Copy Chapter

To use your own domain instead of the default Azure domain:

1. Navigate to the "Custom domains" section in your web app's settings.

2. Follow the Azure Custom Domain Configuration Guide to map your domain to your Azure web app.

Troubleshooting Copy Chapter

If you encounter issues during deployment or while running your EverShop store on Azure:

1. Check the application logs in the Azure portal under "App Service logs"
2. Verify your environment variables are configured correctly
3. Ensure your database connection is working properly
4. Confirm that your PM2 configuration is correct

Performance Optimization Copy Chapter

For optimal performance of your EverShop store on Azure:

1. Enable Azure CDN for faster content delivery
2. Configure auto-scaling based on your expected traffic patterns
3. Use the appropriate App Service pricing tier for your needs
4. Consider adding Redis Cache for improved performance

File: docs/development/deployment/deploy-evershop-to-digitalocean-app-platform.md Copy Chapter

sidebar_position: 12
keywords:

• DigitalOcean deployment
• App Platform hosting
• EverShop cloud deployment
• Node.js PostgreSQL deployment
  sidebar_label: Deploy to DigitalOcean App Platform
  title: Deploy EverShop to DigitalOcean App Platform

Deploy EverShop to DigitalOcean App Platform

This guide provides detailed instructions for deploying EverShop to DigitalOcean App Platform with a managed PostgreSQL database. Follow these steps to get your ecommerce store running in a production environment.

:::tip
Before you go live, run down the Production Checklist — it lists every environment variable EverShop reads at boot, the built-in per-IP rate limits, and what the build and start sequence actually does.
:::

Prerequisites Copy Chapter

Before beginning the deployment process, ensure you have:

• A DigitalOcean account with billing set up
• A registered domain name (for production use)
• A GitHub account
• A GitHub repository containing your EverShop application code

Getting Started Copy Chapter

Prepare Your GitHub Repository Copy Section

While DigitalOcean App Platform supports multiple deployment methods, this tutorial focuses on deployment via GitHub integration. This approach enables continuous deployment whenever you push changes to your repository.

Ensure your package.json file contains the following scripts that DigitalOcean will execute during deployment:

{
  "scripts": {
    "build": "evershop build",
    "start": "evershop start",
    "user:create": "evershop user:create",
    "user:changePassword": "evershop user:changePassword"
  }
}

:::info
evershop build takes no flags. Asset minification is always on in a production build and cannot be turned off.
:::

Create a New DigitalOcean App Copy Section

1. Log in to your DigitalOcean account and navigate to the App Platform dashboard.

2. Click the "Create App" button to begin the setup process.

3. In the "Resources" section, select your GitHub repository containing the EverShop code. If this is your first time connecting GitHub to DigitalOcean, click "Manage Access" to authorize the integration.

4. Configure your deployment settings. You can typically use the default settings, but verify the branch you want to deploy.

5. Click "Next" to proceed to the plan selection. Choose the plan that best fits your requirements. For testing or small-scale deployments, the "Basic" plan is often sufficient.

:::warning
Do not add a database to your app at this stage. EverShop requires PostgreSQL 13 or higher, but DigitalOcean App Platform currently offers PostgreSQL 12 through its integrated database option. We'll create a compatible database separately in the next section.
:::

6. For now, leave the "Environment Variables" section empty. We'll configure these after creating the database.

7. Complete the "Info" and "Review" sections, then finalize your app creation by clicking "Create Resources."

Create a PostgreSQL Database Copy Chapter

EverShop requires PostgreSQL version 13 or higher. Follow these steps to create a compatible managed database:

1. From the DigitalOcean dashboard, click "Databases" in the main navigation menu.

2. Click the "Create Database Cluster" button.

3. Select "PostgreSQL" as the database type and choose version 13 or higher.

4. Select your preferred region, typically the same region as your App Platform deployment.

5. Choose an appropriate plan based on your expected traffic and database usage.

6. After the database is created, navigate to its "Overview" page to find the connection details you'll need for the next steps.

:::warning
For App Platform integration, you must use the "Public Network" connection method, as DigitalOcean App Platform does not currently support private "VPC Network" connections to managed databases. Consider implementing additional security measures such as IP restrictions if your application handles sensitive data.
:::

Configure Your EverShop Application Copy Chapter

Set Up Environment Variables Copy Section

Now that your database is ready, configure your EverShop application with the appropriate connection details:

1. Return to your App Platform dashboard and select your EverShop application.

2. Navigate to the "Settings" tab and find the "App-level environment variables" section.

3. Add the following environment variables, using the values from your database connection details:

• DB_HOST: The hostname of your PostgreSQL database
• DB_PORT: The port number (typically 25060 for DigitalOcean managed PostgreSQL)
• DB_NAME: Your database name
• DB_USER: Your database username
• DB_PASSWORD: Your database password
• DB_SSLMODE: Set to no-verify (or require if you've configured proper SSL)
• EVERSHOP_HOME_URL: Your store's public base URL, e.g. https://your-app.ondigitalocean.app (or your custom domain once configured)
• TRUST_PROXY_HOPS: Set to 1 — App Platform routes every request through its own load balancer

Set the public base URL Copy Section

EVERSHOP_HOME_URL overrides the shop.homeUrl configuration key and is the recommended way to set your production base URL — it lives with the rest of your App Platform environment variables, so changing it needs no code change.

EVERSHOP_HOME_URL=https://your-app.ondigitalocean.app

Everything EverShop emits as an absolute URL depends on it: links in transactional emails, canonical tags, hreflang alternates, and the <loc> entries plus the Sitemap: line in robots.txt. If it is left unset, EverShop falls back to shop.homeUrl and then to http://localhost: — which means customer emails go out pointing at localhost.

:::danger A malformed value stops the app from booting
EVERSHOP_HOME_URL is validated during startup. It must be an absolute http or https URL. A value like your-app.ondigitalocean.app (no scheme), or one using another protocol, throws during bootstrap and the process exits before it listens — the deployment will fail its health check.

Set the full origin with a scheme and no trailing path. Leaving the variable unset is fine; setting it to something invalid is fatal.
:::

:::tip
Update EVERSHOP_HOME_URL when you attach your custom domain. Leaving it on the *.ondigitalocean.app hostname means every email and canonical URL keeps pointing at the platform domain.
:::

Set the proxy hop count Copy Section

TRUST_PROXY_HOPS tells EverShop how many reverse proxies sit in front of the app. It drives Express's trust proxy setting, which determines request.ip — and request.ip is what the built-in rate limiter buckets on.

An unset, empty or non-numeric value falls back to 1. Count the hops that actually terminate and re-forward the connection, and set the variable to that number.

Configure Deployment Commands Copy Section

To ensure your application builds and starts correctly:

1. In the "Settings" tab, select your app component (typically named after your GitHub repository).

2. Navigate to the "Commands" section.

3. Verify that the build and run commands match the scripts in your package.json file:

4. Save your changes. DigitalOcean will automatically redeploy your application with the new configuration.

After the deployment process completes, your EverShop application should be up and running on DigitalOcean App Platform. You can verify this by checking the deployment status:

Create an Administrator Account Copy Chapter

To access the admin panel and manage your store, create an administrator account:

1. From your App Platform dashboard, select your EverShop application.

2. Navigate to the "Console" tab to access a command-line interface.

3. Run the following command to create an admin user, replacing the placeholder values with your desired credentials:

npm run user:create -- --email "[email protected]" --name "Admin User" --password "SecurePassword123!"

4. Once the command completes successfully, access your admin panel by visiting https://<your-app-domain>/admin and log in with your newly created credentials.

Next Steps Copy Chapter

Congratulations! You've successfully deployed EverShop to DigitalOcean App Platform. Here are some additional steps to consider:

Configure Custom Domain Copy Section

For production use, configure your custom domain through the App Platform "Settings" tab under the "Domains" section.

Set Up Continuous Deployment Copy Section

Your application is already configured for automatic deployment when you push changes to your GitHub repository. You can adjust these settings in the "Settings" tab under the "Components" section.

Implement Monitoring Copy Section

Consider setting up monitoring and alerts through DigitalOcean's Monitoring service to keep track of your application's health and performance.

Regular Backups Copy Section

Configure regular database backups through the DigitalOcean Managed Database dashboard to protect your store's data.

Performance Optimization Copy Section

As your store grows, consider scaling your resources in App Platform and optimizing your EverShop application for improved performance.

File: docs/development/deployment/deploy-evershop-to-heroku.md Copy Chapter

sidebar_position: 7
keywords:

• Heroku deployment
• EverShop hosting
• PostgreSQL setup
• Node.js cloud hosting
  sidebar_label: Deploy to Heroku
  title: Deploy EverShop to Heroku

Deploy EverShop to Heroku

This guide provides detailed instructions for deploying an EverShop application on Heroku's cloud platform using the Heroku Command Line Interface (CLI) and a PostgreSQL database add-on.

:::tip
Before you go live, run down the Production Checklist — it lists every environment variable EverShop reads at boot, the built-in per-IP rate limits, and what the build and start sequence actually does.
:::

Prerequisites Copy Chapter

Before beginning the deployment process, ensure you have:

1. An active Heroku account
2. An EverShop project installed and running on your local machine
3. Git installed on your local machine
4. Heroku CLI installed

Step 1: Create a New Heroku App Copy Chapter

1. Log in to the Heroku dashboard.
2. Click the "New" button and select "Create new app" from the dropdown menu.
3. Enter a unique app name, select your preferred region, and click "Create app".

Step 2: Install and Configure Heroku CLI Copy Chapter

1. If you haven't already, download and install the Heroku CLI from the official Heroku documentation.
2. Open your terminal and authenticate with Heroku:

heroku login

Follow the prompts to complete the authentication process.

Step 3: Set Up a PostgreSQL Database Copy Chapter

EverShop requires a PostgreSQL database. Add the Heroku Postgres add-on to your application:

heroku addons:create heroku-postgresql:PLAN_NAME -a YOUR_APP_NAME

:::caution
Replace PLAN_NAME with your desired PostgreSQL plan (e.g., hobby-dev for the free tier). See the Heroku Postgres plans for available options.

Replace YOUR_APP_NAME with your Heroku application name.
:::

Configure Database Connection Copy Section

Heroku provides database credentials as a connection string in the DATABASE_URL environment variable. View this connection string with:

heroku config -a YOUR_APP_NAME

You'll see output similar to:

DATABASE_URL: postgres://username:password@host:port/database_name

Since EverShop requires individual database configuration parameters rather than a connection string, parse the DATABASE_URL and set the following environment variables:

heroku config:set DB_HOST=your_database_host -a YOUR_APP_NAME
heroku config:set DB_PORT=5432 -a YOUR_APP_NAME
heroku config:set DB_USER=your_database_username -a YOUR_APP_NAME
heroku config:set DB_PASSWORD=your_database_password -a YOUR_APP_NAME
heroku config:set DB_NAME=your_database_name -a YOUR_APP_NAME
heroku config:set DB_SSLMODE=no-verify -a YOUR_APP_NAME

:::tip
The values for these environment variables can be extracted from the DATABASE_URL. For example, if your DATABASE_URL is:

postgres://gqdnxqkaxcrbyd:dd3aecf3715167ce8a519c518f637sdfcb9ebb0dda3723d050e8a3b8a7cf19fc789@ec2-52-205-11-146.compute-1.amazonaws.com:5432/d468v1qsdfnb0arsqf

Then your environment variables would be:

DB_HOST=ec2-52-205-11-146.compute-1.amazonaws.com
DB_PORT=5432
DB_USER=gqdnxqkaxcrbyd
DB_PASSWORD=dd3aecf3715167ce8a519c518f637sdfcb9ebb0dda3723d050e8a3b8a7cf19fc789
DB_NAME=d468v1qsdfnb0arsqf

:::

Step 4: Prepare Your Local Project Copy Chapter

Assuming you have an EverShop project ready for deployment, you'll need to make a few configuration changes to ensure compatibility with Heroku.

A typical EverShop project structure looks like:

├── .evershop     # Production build files
├── .log          # Application logs
├── extensions    # Custom extensions
├── media         # Uploaded images and media
├── themes        # Custom themes
├── node_modules  # Node.js dependencies
├── public        # Static public files
├── .env          # Environment variables (local only)
├── package.json  # Project configuration
└── README.md     # Documentation

Specify Node.js and NPM Versions Copy Section

Add Node.js and NPM version specifications to your package.json:

{
  "engines": {
    "node": "20.x",
    "npm": "9.x"
  }
}

Configure Scripts for Heroku Copy Section

Update your package.json with the necessary scripts for Heroku deployment:

{
  "scripts": {
    "build": "evershop build",
    "start": "evershop start",
    "user:create": "evershop user:create"
  }
}

:::info
evershop build takes no flags. Asset minification is always on in a production build and cannot be turned off.
:::

Set the Public Base URL Copy Section

EVERSHOP_HOME_URL overrides the shop.homeUrl configuration key and is the recommended way to set your production base URL on Heroku — it is a config var like any other, so changing it needs no redeploy of your code.

heroku config:set EVERSHOP_HOME_URL=https://YOUR_APP_NAME.herokuapp.com -a YOUR_APP_NAME

Everything EverShop emits as an absolute URL depends on it: links in transactional emails, canonical tags, hreflang alternates, and the <loc> entries plus the Sitemap: line in robots.txt. If it is left unset, EverShop falls back to shop.homeUrl and then to http://localhost: — which means customer emails go out pointing at localhost.

:::danger A malformed value stops the dyno from booting
EVERSHOP_HOME_URL is validated during startup. It must be an absolute http or https URL. A value like YOUR_APP_NAME.herokuapp.com (no scheme), or one using another protocol, throws during bootstrap and the process exits before it binds to $PORT — Heroku will report an R10 Boot timeout or crash the dyno.

Set the full origin with a scheme and no trailing path. Leaving the variable unset is fine; setting it to something invalid is fatal.
:::

:::tip
Update EVERSHOP_HOME_URL when you attach a custom domain, otherwise every email and canonical URL keeps pointing at herokuapp.com.
:::

Set the Proxy Hop Count Copy Section

Heroku's router sits in front of every dyno, so EverShop only sees the real client IP through X-Forwarded-For. TRUST_PROXY_HOPS tells EverShop how many proxies to trust. It drives Express's trust proxy setting, which determines request.ip — and request.ip is what the built-in rate limiter buckets on.

heroku config:set TRUST_PROXY_HOPS=1 -a YOUR_APP_NAME

An unset, empty or non-numeric value falls back to 1. Count the hops that actually terminate and re-forward the connection, and set the variable to that number.

Configure Build Behavior Copy Section

Control how Heroku builds your application with these environment variables:

# Skip installing devDependencies (recommended for production)
heroku config:set NPM_CONFIG_PRODUCTION=true -a YOUR_APP_NAME

# Use 'npm install' instead of 'npm ci' (if you encounter issues with npm ci)
heroku config:set USE_NPM_INSTALL=true -a YOUR_APP_NAME

:::info
Heroku automatically sets NODE_ENV=production for all deployed applications.
:::

Create a .gitignore File Copy Section

Create a .gitignore file to exclude unnecessary files from deployment:

.evershop
.log
node_modules
.env

Step 5: Deploy Your Application Copy Chapter

Initialize Git Repository Copy Section

If your project isn't already in a Git repository:

git init

Commit Your Changes Copy Section

Add and commit all files:

git add .
git commit -m "Prepare EverShop for Heroku deployment"

Connect to Heroku Remote Copy Section

Link your local repository to your Heroku app:

heroku git:remote -a YOUR_APP_NAME

Deploy to Heroku Copy Section

Push your code to deploy:

git push heroku main

If your primary branch is named master instead of main, use:

git push heroku master

Heroku will automatically detect your Node.js application, install dependencies, run the build script, and start your application. You can monitor the deployment process in your terminal.

Once deployed, you can access your application at:

https://YOUR_APP_NAME.herokuapp.com

Step 6: Create an Administrator Account Copy Chapter

After your first deployment, create an administrator account to access the admin panel:

heroku run npm run user:create -- --email "[email protected]" --name "Admin User" --password "SecurePassword123!" -a YOUR_APP_NAME

:::caution
Replace the example credentials with a secure email, name, and strong password.
:::

Once created, you can access the admin panel at:

https://YOUR_APP_NAME.herokuapp.com/admin

Troubleshooting and Maintenance Copy Chapter

Viewing Application Logs Copy Section

Monitor your application logs with:

heroku logs --tail -a YOUR_APP_NAME

Scaling Your Application Copy Section

As your store grows, you may need to scale your application:

heroku ps:scale web=2 -a YOUR_APP_NAME

Managing Database Backups Copy Section

Create regular backups of your PostgreSQL database:

heroku pg:backups:capture -a YOUR_APP_NAME

Updating Your Application Copy Section

To deploy updates, simply commit your changes and push to Heroku:

git add .
git commit -m "Update application"
git push heroku main

Conclusion Copy Chapter

Congratulations! You've successfully deployed EverShop to Heroku. Your ecommerce application is now accessible to customers worldwide, backed by Heroku's reliable cloud infrastructure.

File: docs/development/deployment/production-checklist.md Copy Chapter

sidebar_position: 2
keywords:

• EverShop production checklist
• environment variables
• rate limiting
• EVERSHOP_HOME_URL
• TRUST_PROXY_HOPS
• production deployment
  sidebar_label: Production Checklist
  title: Production Checklist

Production Checklist

This page is the pre-launch pass. Whichever platform you deploy to — AWS, Azure, DigitalOcean, Heroku or your own machine — the same set of environment variables governs how the store boots, and the same rate limits govern how it behaves under load.

Read it top to bottom once before your first production start, and again whenever you move the store to a new host or put a CDN in front of it.

Environment variables Copy Chapter

EverShop is configured for deployment through environment variables. On a server they normally live in a .env file in the project root (the file evershop install writes) or in your platform's configuration panel — both end up in process.env, which is all EverShop reads.

Two of these have failure modes worth knowing before you set them: EVERSHOP_HOME_URL aborts the boot if it is malformed, and TRUST_PROXY_HOPS silently changes who your rate limits apply to. Both are covered in detail below the table.

**Any unset or unrecognized value means no TLS at all.** A typo here does not error; it silently sends your credentials in the clear. |

| DB_SSLROOTCERT``DB_SSLCERT``DB_SSLKEY | — | Filesystem paths to a CA bundle / client certificate / client key. Read only in the verifying DB_SSLMODE modes. A path that does not exist throws at startup when the connection pool is created. |
| **Server** | | |
| PORT | 3000 | Port the HTTP server binds to. A non-numeric value falls back to 3000 rather than failing — if your platform assigns a port dynamically, make sure it is exported before the process starts. |
| NODE_ENV | set by the CLI | You do not need to set this. evershop start and evershop build force production; evershop dev forces development. A value you export is overwritten by the CLI for those commands. |
| EVERSHOP_HOME_URL | shop.homeUrl, then localhost | **Validated at boot — a malformed value is fatal.** The store's public base URL, used for every absolute URL the store emits. See below. |
| TRUST_PROXY_HOPS | 1 | Number of reverse proxies in front of the app. Determines request.ip, and therefore which bucket the rate limiter counts a request into. See below. |
| **Tokens and secrets** | | |
| JWT_ADMIN_SECRET | — | Signing keys for the token-based REST authentication endpoints (POST /api/user/tokens, /api/user/token/refresh, /api/customer/tokens, /api/customer/token/refresh, /api/user/session/tokens).

There is no default and no boot-time check: the endpoints throw `JWT secret for … is not configured` the first time they are called. If you use the REST API from a headless frontend or a mobile app, set all four to long, independent random strings. Rotating one invalidates every token signed with it.
    
    Cookie-session logins to the admin panel and the storefront do not use these. |

| JWT_ADMIN_REFRESH_SECRET | — | |
| JWT_CUSTOMER_SECRET | — | |
| JWT_CUSTOMER_REFRESH_SECRET | — | |
| JWT_ISSUER | evershop | The iss claim on issued tokens. |
| JWT_ADMIN_TOKEN_EXPIRY
JWT_ADMIN_REFRESH_TOKEN_EXPIRY
JWT_CUSTOMER_TOKEN_EXPIRY
JWT_CUSTOMER_REFRESH_TOKEN_EXPIRY | 900
54000
1800
108000 | Token lifetimes in seconds (15 min / 15 h / 30 min / 30 h). |
| ORDER_TRACKING_TOKEN_SECRET | — | Signs the anonymous order-tracking links embedded in shipment emails. If unset, those links cannot be generated and the tracking page renders "this link is no longer valid". Set it if guests can place orders. |
| Images | | |
| IMAGE_ALLOWED_HOSTS | empty | Comma-separated allowlist of hosts the /images optimization proxy may fetch from. It is a strict allowlist: it blocks SSRF against internal addresses and stops the endpoint being used as a free image proxy for third-party sites.

**EverShop logs a warning at boot when this is unset** and no cloud storage host can be derived from your configuration. With nothing allowed, only local `media`, `public` and theme images are optimized; external images are refused. When S3, Azure or GCS file storage is configured, that provider's host is allowed automatically — you do not need to repeat it here. |

| Logging | | |
| LOG_FILE | console | Path to a log file. When set, log output goes to that file instead of the console — check it before you conclude the app is silent. Ignored in debug mode (evershop dev, or --debug), which always logs to the console. |
| LOGGER_LEVEL | warn | Minimum level to record: error, warn, info, http, verbose, debug, silly. The default of warn means informational messages are dropped in production. Debug mode overrides this to silly. |
| Cloud file storage — only needed for the provider you selected in Admin → Settings. See File Storage. | | |
| AWS_BUCKET_NAME
AWS_REGION
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_S3_ENDPOINT
AWS_S3_FORCE_PATH_STYLE
AWS_S3_BASE_URL | — | Amazon S3 and S3-compatible services. Omit the key pair to use the AWS SDK's default credential chain (instance role, IRSA, shared config) — the recommended setup on EC2 and EKS. AWS_S3_ENDPOINT plus AWS_S3_FORCE_PATH_STYLE cover R2, MinIO and Spaces; AWS_S3_BASE_URL serves files through a CDN instead of the bucket host. |
| GCS_BUCKET_NAME
GCS_BASE_URL | — | Google Cloud Storage. Credentials come from Application Default Credentials (an attached service account, or GOOGLE_APPLICATION_CREDENTIALS) unless you paste a service-account key in the admin settings. |
| AZURE_STORAGE_CONNECTION_STRING
AZURE_STORAGE_CONTAINER_NAME
AZURE_STORAGE_BASE_URL | container: images | Azure Blob Storage. The container is created on first use if it does not exist. |

:::info
Anything set through an environment variable or config/<env>.json wins over the matching admin setting, and the admin form shows those fields as read-only. That is deliberate: it lets infrastructure pin credentials that a store operator must not be able to change from the browser.
:::

:::tip Installer variables
evershop install also reads ADMIN_FULLNAME, ADMIN_EMAIL and ADMIN_PASSWORD, and skips the matching prompt when one is present. Useful for scripting an unattended first install. They have no effect on a running store.
:::

`EVERSHOP_HOME_URL` — validated, and fatal when wrong Copy Section

This is the recommended way to set your store's public base URL. It overrides the shop.homeUrl configuration key, so you can change the domain without editing a config file or rebuilding.

EVERSHOP_HOME_URL="https://your-store.com"

Everything the store emits as an absolute URL is derived from it:

• links in transactional emails (order confirmations, shipment notifications, password resets)
• <loc> entries in sitemap.xml and the absolute Sitemap: line in the generated robots.txt
• canonical tags and hreflang alternates on multi-language stores

Left unset, EverShop falls back to shop.homeUrl and then to http://localhost:$PORT. That fallback is the classic production bug: the store works fine in a browser, and every order confirmation emails a localhost link to the customer.

:::danger A malformed value stops the boot
The value is validated during module bootstrap. It must parse as a URL and use the http or https protocol. your-store.com (no scheme) and ftp://your-store.com both throw, and the process exits before it starts listening.

An unset or empty value is allowed — it just falls back. Only a set but invalid value is fatal. If a deploy suddenly fails to come up right after you touched this variable, that is where to look.
:::

Set the full origin, with the scheme and without a trailing slash or path. Update it when you move from a platform-assigned hostname to your custom domain, and again if you switch from http to https.

`TRUST_PROXY_HOPS` — who the rate limiter sees Copy Section

Every deployment in this section runs behind at least one proxy. EverShop only learns the real client address from the X-Forwarded-For header, and it only trusts as much of that header as you tell it to.

TRUST_PROXY_HOPS sets Express's trust proxy to a hop count. That determines request.ip, and request.ip is the key the rate limiter buckets on.

**Set too high** and the app trusts an entry in `X-Forwarded-For` that the client supplied. A client can then present a fresh fake IP on every request and never hit a limit at all. |

Count the hops that actually terminate and re-forward the connection, and set the variable to exactly that number. An unset, empty, negative or non-integer value falls back to 1.

Built-in rate limits Copy Chapter

EverShop ships a per-client-IP rate limiter, mounted early in the middleware stack — before session lookup and before any database work — so a flood is shed before it consumes a connection from the pool.

`/customer/login`
    `/admin/user/login`
    `/api/customers` (registration)
    `/api/customers/reset-password`
    `/api/customers/password` | **8 requests per 15 minutes** per IP |

A leading locale prefix is stripped before matching, so /fr/customer/login lands in the auth tier just like /customer/login.

Exempt paths Copy Section

These never count against any limit:

• Static assets — any path ending in a known asset extension: .js, .mjs, .cjs, .css, .map, .png, .jpg, .jpeg, .gif, .svg, .webp, .avif, .ico, .woff, .woff2, .ttf, .eot, .txt, .xml, .json. (This is why /robots.txt and /sitemap.xml are also exempt.)
• Hot module replacement — /__webpack_hmr… and any .hot-update path.
• /backend/ — the admin development bundle.
• /health and /healthz — reserved for uptime probes, so a monitor polling every few seconds never exhausts a bucket.

:::caution
/health and /healthz are exempt from rate limiting, but EverShop core does not define them as routes — a request to either returns a 404 unless you add the route yourself in an extension. If your platform requires a health-check endpoint, point it at one of these two paths and implement it, so the probe traffic stays exempt.
:::

The 429 contract Copy Section

When a limit is exceeded, the response is 429 Too Many Requests with:

• a Retry-After header, in seconds — 60 for the page and API tiers, 900 for the auth tier
• standard RateLimit-* headers on every response, so a well-behaved client can back off before it is throttled (the legacy X-RateLimit-* headers are not sent)
• a JSON body for /api/** paths, matching EverShop's normal error envelope:

{
  "error": {
    "status": 429,
    "message": "Too many requests. Please slow down and try again later."
  }
}

• a plain-text body for page requests

What you cannot change Copy Section

These limits are hardcoded and not operator-configurable. There is no config key and no environment variable for the windows, the thresholds or the tiers. They are deliberately generous — sized so that an office or a mobile carrier sharing one NAT address still browses comfortably — and exist as a capacity safety net rather than as a tunable policy.

The limiter is skipped when NODE_ENV=test, which keeps integration suites deterministic. That is not an escape hatch for production: evershop start forces NODE_ENV=production, so a running store always has the limiter active.

:::warning A per-IP limit is not DDoS protection
Per-IP limits stop a single abusive source. A distributed flood arrives from thousands of addresses and each one stays under the threshold. If that is in your threat model, put a WAF or CDN with edge rate limiting in front of the store — and remember to raise TRUST_PROXY_HOPS when you do.
:::

Build and start Copy Chapter

Two commands, in this order:

npm run build
npm run start

evershop build compiles the production bundles for every route. It takes no flags — asset minification is always on for a production build and cannot be disabled. Run it on every deploy, after npm install, and re-run it whenever you change a theme, add an extension or upgrade EverShop.

evershop start boots the server in production mode. It sets NODE_ENV=production itself, loads .env, runs module bootstrap, and binds to $PORT (default 3000).

Migrations run on start Copy Section

Database migrations are applied automatically during startup, after bootstrap and before the server accepts requests. There is no separate migrate command to run and nothing to schedule.

The practical consequences:

• The database user in DB_USER needs DDL privileges — CREATE, ALTER, DROP — permanently, not just at install time.
• Take a backup before starting a new version. Migrations are not reversible; rolling the application back does not roll the schema back.
• On a multi-instance deployment, be aware that every instance runs migrations at boot. Roll instances one at a time rather than restarting the whole fleet at once.
• The very first start on an empty database also creates the schema, so a fresh deploy has a longer cold start than subsequent ones.

Creating the first administrator is a separate, explicit step — evershop install does it locally, and on a server you run:

npm run user:create -- --email "[email protected]" --name "Admin" --password "a-strong-password"

Final pass before launch Copy Chapter

• EVERSHOP_HOME_URL is set to the real public origin, with https:// and no trailing slash — and a test email actually links to it.
• TRUST_PROXY_HOPS matches the real number of proxies. Confirm it by checking that different clients produce different addresses in your logs.
• DB_SSLMODE is one of the verifying modes, not left unset.
• The four JWT secrets are set to independent random strings if you use the REST API; ORDER_TRACKING_TOKEN_SECRET is set if guests can order.
• IMAGE_ALLOWED_HOSTS is set, or cloud file storage is configured — check the boot log for the warning.
• LOG_FILE points somewhere you will actually look, and log rotation is configured for it.
• Uploaded media is on cloud storage, or on a volume that survives a redeploy. See File Storage.
• Automated database backups are on, and you have restored one at least once.
• No hand-written public/robots.txt or public/sitemap.xml is shadowing the generated ones. See Static File Serving.
• Store settings — currency, timezone, units, languages, tax — are set in Admin → Settings. See Store Settings.
• Demo seed data has not been run against the production database.
• npm run build completed without errors on the exact commit you are deploying.

File: docs/development/getting-started/installation-guide.md Copy Chapter

sidebar_position: 10
keywords:

• EverShop installation
  sidebar_label: Installation Guide
  title: EverShop Installation Guide

Installation guide

The following installation guides will guide you step-by-step to create a new EverShop project and get it started.

:::info

Please check this document for the system requirements list.

:::

Install EverShop Using `create-evershop-app` command Copy Chapter

npx create-evershop-app my-evershop-app

The create-evershop-app command will create a new folder named my-evershop-app and install all of the dependencies for you.

Install EverShop Using Docker Copy Chapter

You can get started with EverShop in minutes by using the Docker image. The Docker image is a great way to get started with EverShop without having to worry about installing dependencies or configuring your environment.

curl -sSL https://raw.githubusercontent.com/evershopcommerce/evershop/main/docker-compose.yml > docker-compose.yml
docker-compose up -d

The Docker image will start a fresh EverShop installation with the default configuration. You can access the site at http://localhost:3000 and the admin panel at http://localhost:3000/admin.

:::info
To create a new admin user, terminal into the Docker app container and run the following command:

npm run user:create -- --email "your email" --password "your password" --name "your name"

:::

:::caution
The public Docker image is for installing EverShop in your local environment only. If you are looking for a development solution, please check the development section below.
:::

Install EverShop manually using Npm Copy Chapter

Step 1: Install The @evershop/evershop Npm Package Copy Section

@evershop/evershop is the core of the EverShop platform. It contains all of the core modules like catalog, checkout, order.

npm init --init-type=module -y
npm install @evershop/evershop

:::info
EverShop is an ES-modules (ESM) project and requires "type": "module" in your project's package.json. npm 11 and newer write "type": "commonjs" into the package.json generated by npm init -y — with that value, npm run build fails on every page with Module parse failed: 'import' and 'export' may appear only with 'sourceType: module'. The npm pkg set type=module command sets the correct module type. Projects created with create-evershop-app already have it.
:::

Step 2: Install the core Npm scripts Copy Section

Open the package.json file and add the following scripts:

{
  "scripts": {
    "setup": "evershop install",
    "build": "evershop build",
    "start": "evershop start",
    "dev": "evershop dev",
    "seed": "evershop seed",
    "start:debug": "evershop start --debug",
    "user:create": "evershop user:create",
    "user:changePassword": "evershop user:changePassword",
    "theme:create": "evershop theme:create",
    "theme:active": "evershop theme:active",
    "theme:twizz": "evershop theme:twizz",
    "theme:status": "evershop theme:status",
    "theme:uninstall": "evershop theme:uninstall",
    "theme:export-content": "evershop theme:export-content"
  }
}

:::info
The six theme:* scripts are required if you plan to work with themes — creating one, activating it, or overriding its components. The theme documentation refers to them by their npm run names. See the Command-Line Interface reference for what each one does and which flags it accepts.

When you pass flags through npm run, separate them with --, e.g. npm run theme:active -- boutique --dry-run.
:::

Step 3: Run the installation script Copy Section

Before running this script, make sure that you have an empty Postgres database ready for EverShop.

:::info
Please check this document for the system requirements list.
:::

The interactive setup wizard will prompt you for:

1. Database connection details — host, port, database name, user, and password
2. Admin user details — full name, email, and password (minimum 8 characters, must contain at least one letter and one digit)

Once you provide this information, the setup script will:

• Create a .env file in your project root with the database connection settings
• Create the media and public directories
• Set up the database schema (create all required tables)
• Run all database migrations
• Create your administrator account

npm run setup

:::info
The .env file created by the setup script contains your database credentials:

DB_HOST="localhost"
DB_PORT="5432"
DB_NAME="evershop"
DB_USER="postgres"
DB_PASSWORD="your_password"
DB_SSLMODE="disable"

You can edit this file later to change your database connection settings. See the Database documentation for more options including SSL configuration.
:::

Step 4: Folder permission Copy Section

EverShop needs to write some files to the disk. So you need to make sure that the following folders have the write permission:

• public/
• .evershop
• .log
• media

Step 5: Run the `build` command to build the site Copy Section

npm run build

Step 6: Run the `start` command to start your store in production mode Copy Section

npm run start

Your site will start at http://localhost:3000.

Admin panel can be accessed at http://localhost:3000/admin.

:::info
By default EverShop will start at port 3000. You can change the port by setting the PORT environment variable.
:::

Configuring Your Store Copy Chapter

Most of what a merchant changes day to day is not a config.json key. Currency, timezone, weight and length units, store languages, branding (logo, favicon), catalog display options, tax rounding and the cloud file-storage provider are all stored in the database and edited from Admin → Settings. They take effect without a restart and without a rebuild.

config/<env>.json stays for deployment concerns: database credentials, the active theme, session secrets and extension wiring — things a developer sets and a redeploy changes.

See Store Settings for the full split, the getSetting / getSettingSync API, and how to migrate extension code that still reads a config key.

Upgrade EverShop Copy Chapter

To upgrade EverShop to the latest version:

npm install @evershop/evershop@latest

npm run build

npm run start

Database migrations are run automatically when the application starts, so any schema changes in the new version are applied for you.

:::warning Major upgrades can break themes and extensions
A minor or patch upgrade is normally a drop-in replacement. A major upgrade is not: the core React version, component APIs and public import paths can change, and your custom theme and extensions run against them.

Before upgrading a live store, read the release notes for the version you are moving to, upgrade a staging copy first, and take a database backup — migrations are applied automatically on the first start and are not reversible.

The most recent example is EverShop 2.2, which moved the framework from React 17 to React 19. Most of those changes fail silently at runtime rather than at build time. See Upgrading To React 19 for the full list of breaking changes and the fix for each one.
:::

Demo Data Seeding Copy Chapter

After installation, you can populate your store with demo data using the seed command. This is useful for development and testing.

npm run seed

This command will populate your store with sample products, categories, and other data.

:::info
Demo data seeding is intended for development and testing environments only. Do not use it in production.
:::

For Developers Copy Chapter

If you are a developer and want to start the project in development mode, there are some additional steps you need to follow.

Install Additional Dev Dependencies Copy Section

To run the project in development mode, you need to install additional dependencies. These are not required for production but are essential for development:

npm install --save-dev @types/node typescript @parcel/watcher @types/config @types/express @types/pg @types/react execa

Adding the workspace configuration Copy Section

Open the package.json and add the following configuration:

{
  "workspaces": ["extensions/*", "themes/*"]
}

This allows each extension and theme to function as an independent package with its own dependencies.

Start the project in development mode Copy Section

npm run dev

Your store will start at http://localhost:3000 with hot-reloading enabled. Changes to React components update instantly in the browser.

The debug mode Copy Section

The start:debug script (already added in Step 2) starts the production server with debug logging enabled:

npm run start:debug

This outputs detailed middleware execution timings and request processing information.

:::info
Debug mode is enabled by default when you run the dev command, so you don't need to use start:debug during development.
:::

Dockerize Your Project Copy Section

Dockerizing your EverShop project allows you to create a portable, self-contained environment for your application. Below is a guide to creating your own Docker image and managing persistent data like media files.

Handling Persistent Media Files

When you dockerize your application, it's crucial to handle the media directory correctly. This directory contains user-uploaded files (like product images) and should not be copied directly into the Docker image. If you do, any uploaded files will be lost whenever the container is rebuilt.

There are two primary approaches for managing media files:

1. Docker Volumes: This approach mounts a directory from your host machine into the container. Files are stored on the host, so they persist even if the container is removed. This is suitable for single-server deployments or local development.

2. Cloud Storage: This approach uses a cloud storage service like Amazon S3, Azure Blob Storage or Google Cloud Storage. This decouples file storage from your application container entirely, which is essential for auto-scaling environments and provides better durability and performance.

:::caution Production Recommendation
For any production environment, we strongly recommend using cloud storage. This approach is more scalable, reliable, and secure than using local volumes. It prevents data loss, simplifies backups, and is essential if you ever plan to run your application across multiple servers.

Amazon S3, Azure Blob Storage and Google Cloud Storage are built into EverShop core — there is no extension to install. Pick the provider in Admin → Settings → File Storage and fill in its credentials there, or pin them from config/<env>.json or environment variables when your infrastructure manages them. The S3 provider also drives any S3-compatible service (Cloudflare R2, MinIO, DigitalOcean Spaces) through a custom endpoint.

See File Storage for the provider settings, the credential precedence rules, and how to register a provider of your own.
:::

1. Building Your Docker Image

Here is an example Dockerfile. Note that we have removed the COPY media ./media line.

FROM node:20-alpine
WORKDIR /app
RUN npm install -g npm@10
COPY package*.json .
# Copy your custom theme.
COPY themes ./themes

# Copy your custom extensions.
COPY extensions ./extensions

# Copy your config.
COPY config ./config

# DO NOT copy the media folder. It will be handled by a volume.

# Copy your public files.
COPY public ./public

# We must copy translations to the image as they are required for the build.
COPY translations ./translations

# Run npm install.
RUN npm install

# Build assets.
RUN npm run build

EXPOSE 3000
CMD ["npm", "run", "start"]

2. Using Docker Compose with a Volume

This docker-compose.yml file demonstrates how to build the image and attach a volume for the media directory.

version: "3.8"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    restart: always
    volumes:
      - ./media:/app/media # Mounts the host's media folder to the container
    environment:
      DB_HOST: database
      DB_PORT: 5432
      DB_PASSWORD: postgres
      DB_USER: postgres
      DB_NAME: postgres
    networks:
      - myevershop
    depends_on:
      - database
    ports:
      - 3000:3000

  #The postgres database:
  database:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
      POSTGRES_DB: postgres
    ports:
      - "5432:5432"
    networks:
      - myevershop

networks:
  myevershop:
    name: MyEverShop
    driver: bridge

volumes:
  postgres-data:

With this configuration, any files uploaded to your application will be saved in the media folder on your host machine, ensuring they are not lost.

import Sponsors from '@site/src/components/Sponsor';

npm install --save-dev @types/node typescript @parcel/watcher @types/config @types/express @types/pg @types/react execa

npm install --save-dev @types/react@19 @types/react-dom@19
npm ls @types/react

{
  "overrides": {
    "@types/react": "^19.1.2",
    "@types/react-dom": "^19.0.0"
  }
}

node --version
# Should output: v20.x.x or higher

npm --version
# Should output: 9.x.x or higher

psql --version
# Should output: psql (PostgreSQL) 13.x or higher

df -h

wmic logicaldisk get size,freespace,caption

catalog
├── api
│   ├── createProduct
│   │   ├── ... // Middleware functions
│   │   └── route.json
│   ├── updateProduct
│   │   ├── ... // Middleware functions
│   │   └── route.json
│   ├── createCategory
│   │   ├── ... // Middleware functions
│   │   └── route.json
│   ├── updateCategory
│   │   ├── ... // Middleware functions
│   │   └── route.json
│   ├── createAttribute
│   │   ├── ... // Middleware functions
│   │   └── route.json
│   └── updateAttribute
│       ├── ... // Middleware functions
│       └── route.json

├── createProduct
│   ├── [context]bodyParser[auth].ts
│   ├── saveProduct.ts
│   └── route.json

{
  "methods": ["DELETE"],
  "path": "/products/:id",
  "access": "private"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "short_description": {
      "type": "string"
    },
    "url_key": {
      "type": "string",
      "pattern": "^\\S+$"
    },
    "meta_title": {
      "type": "string"
    },
    "meta_description": {
      "type": "string"
    },
    "meta_keywords": {
      "type": "string"
    },
    "status": {
      "type": ["integer", "string"],
      "enum": [0, 1, "0", "1"]
    },
    "sku": {
      "type": "string"
    },
    "price": {
      "type": ["string", "number"],
      "pattern": "^\\d+(\\.\\d{1,2})?$"
    },
    "weight": {
      "type": ["string", "number"],
      "pattern": "^[0-9]+(\\.[0-9]{1,2})?$"
    },
    "qty": {
      "type": ["string", "number"],
      "pattern": "^[0-9]+$"
    },
    "manage_stock": {
      "type": ["string", "number"],
      "enum": [0, 1, "0", "1"]
    },
    "stock_availability": {
      "type": ["string", "number"],
      "enum": [0, 1, "0", "1"]
    },
    "group_id": {
      "type": ["string", "integer"],
      "pattern": "^[0-9]+$"
    },
    "visibility": {
      "type": ["integer", "string"],
      "enum": [0, 1, "0", "1"]
    },
    "images": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "attributes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "attribute_code": {
            "type": "string"
          },
          "value": {
            "type": ["string", "array"],
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "categories": {
      "type": "array",
      "items": {
        "type": ["string", "integer"],
        "pattern": "^[0-9]+$"
      }
    },
    "options": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "option_name": {
            "type": "string"
          },
          "option_type": {
            "type": "string",
            "enum": ["select", "multiselect"]
          },
          "is_required": {
            "type": ["string", "integer"],
            "enum": [0, 1, "0", "1"],
            "default": 0
          },
          "values": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string"
                },
                "extra_price": {
                  "type": ["string", "number"],
                  "pattern": "^\\d+(\\.\\d{1,2})?$"
                }
              }
            }
          }
        },
        "required": ["option_name", "option_type", "values"],
        "additionalProperties": true
      }
    }
  },
  "required": [
    "name",
    "meta_title",
    "url_key",
    "status",
    "sku",
    "qty",
    "price",
    "weight",
    "group_id",
    "visibility"
  ],
  "additionalProperties": true
}

{
  "error": {
    "status": 429,
    "message": "Too many requests. Please slow down and try again later."
  }
}

├── .env # Database credentials and other environment variables
├── .evershop # Built files and cache
├── config
│     ├ default.json # Your custom configuration
├── extensions # Your custom modules
├── media # Uploaded files (images, etc.)
├── public # Static assets (CSS, JS, images)
├── node_modules # Project dependencies
├── themes # Your custom themes
├── translations # Locale dictionaries (one folder per locale, CSV files)
└── package.json

{
  "name": "my-evershop-store",
  "version": "1.0.0",
  "workspaces": [
    "extensions/*",
    "themes/*"
  ]
}

├── extensions
│   ├── my-custom-extension
│   │   ├── src/
│   │   │   └── bootstrap.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── another-extension
│       ├── src/
│       │   └── bootstrap.ts
│       ├── package.json
│       └── tsconfig.json

const reserved = getRoutes()
  .filter((r) => !r.isAdmin && !r.isApi && /^\/[a-zA-Z0-9-]+$/.test(r.path))
  .map((r) => r.path);

URL key "blog" is reserved by a system route and would be unreachable.

import { addProcessor } from '@evershop/evershop/lib/util/registry';

export default function bootstrap() {
  addProcessor('blogPostDataBeforeCreate', async function (data) {
    // `this` is the processor context — do not use an arrow function here.
    return data;
  });

  addProcessor('createBlogPostDataJsonSchema', function (schema) {
    schema.properties.reviewed_by = { type: ['string', 'null'] };
    return schema;
  });
}

readingTime: ({ readingTime: cached, description }) =>
  typeof cached === 'number' && cached > 0 ? cached : readingTime(description)

export function resolveReactor(
  request: EvershopRequest,
  response?: EvershopResponse,
  issue = false
): string | null;

export const REACTION_TYPES = ['like', 'love', 'clap', 'insightful'] as const;

type BlogPost {
  blogPostId: Int
  uuid: String!
  status: Int!
  name: String!
  urlKey: String!
  shortDescription: String
  description: JSON
  thumbnail: String
  publishedAt: String
  readingTime: Int!
  commentCount: Int!
  reactions: [BlogReactionCount!]!
  url: String!
  category: BlogCategory
  author: BlogAuthor
  tags: [BlogTag!]!
  related(limit: Int = 3): [BlogPost!]!
  metaTitle: String
  metaDescription: String
  comments: [BlogComment!]!
}

registerWidget({
  type: 'featured_blogs',
  name: 'Featured blogs',
  description: 'A list of featured blog posts',
  category: 'content',
  icon: 'Newspaper',
  enabled: true,
  defaultSettings: {
    eyebrow: '',
    heading: '',
    subText: '',
    postUuids: [],
    count: 3,
    columns: 3
  }
});

const ordered = uuids.map((u) => byUuid.get(u)).filter(Boolean);

export const BlogUrn = {
  post: (uuid: string) => UrnService.build('blog', 'post', uuid),
  category: (uuid: string) => UrnService.build('blog', 'category', uuid),
  tag: (uuid: string) => UrnService.build('blog', 'tag', uuid)
};

registerLinkLoader('blog', 'post', blogLinkLoader('blog_post', 'blogPostView'));
registerLinkLoader('blog', 'category', blogLinkLoader('blog_category', 'blogCategoryView'));
registerLinkLoader('blog', 'tag', blogLinkLoader('blog_tag', 'blogTagView'));

function makeMetafieldFolder(ownerType: string) {
  return async function foldMetafields(data) {
    if (data && data.metafields !== undefined) {
      data.meta_data = await validateMetafields(ownerType, data.metafields);
    }
    return data;
  };
}

addProcessor('blogPostDataBeforeCreate', makeMetafieldFolder('blog_post'));
addProcessor('blogPostDataBeforeUpdate', makeMetafieldFolder('blog_post'));

registerSitemapCollector(
  createEntityCollector({
    name: 'blog-posts',
    table: 'blog_post',
    entityType: 'blog_post',
    where: 'e.status = 1',
    changefreq: 'weekly',
    priority: 0.5
  })
);