Payload CMS installation

Local Installation

The local installation is recommended when you want to customize the template, develop new features, or test your store before deploying it to production.

Prerequisites

Make sure the following software is installed on your computer:

Node.js
pnpm
PostgreSQL
Git (optional)

You can verify Node.js and pnpm with:

node -v
pnpm -v

Installing Payload CMS Locally

Extract the Template

Extract the downloaded main ZIP file into a folder on your computer.

For example:
```
C:\Users\YourName\Desktop\main
```
Open Command Prompt or Terminal inside the project folder.
Install Dependencies

Run the following command to install all required project dependencies:
Terminal window
```
pnpm i
```
Wait until the installation completes successfully.

Important: Make sure pnpm i finishes without errors before continuing.
Create a PostgreSQL Database

Create a new PostgreSQL database for the application.

You can use pgAdmin, DBeaver, PostgreSQL CLI, or another PostgreSQL management tool.

Example database details:
```
Database: ecommerce
Username: postgres
Password: your-password
Host: 127.0.0.1
Port: 5432
```
If you want to create the database using the PostgreSQL command line, navigate to the PostgreSQL bin directory:
Terminal window
```
cd "C:\Program Files\PostgreSQL\18\bin"
```
Connect to PostgreSQL

Run:
Terminal window
```
psql -h 127.0.0.1 -U postgres
```
Enter your PostgreSQL password when prompted.
Create the Database

Inside the PostgreSQL console, create your database:
```
CREATE DATABASE ecommerce;
```
You can verify the database was created successfully with:
```
\l
```
Exit PostgreSQL with:
```
\q
```

Configure Environment Variables

Open the .env file in the project root.

Add your PostgreSQL connection details and other required configuration values.

Example:

DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/ecomnew71
PAYLOAD_SECRET=091838d33373e774atyty
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
PAYLOAD_PUBLIC_SERVER_URL =http://localhost:3000
SERVER_URL=https://payloadecommerce.codenik.in
SMTP_HOST=smtp.gmail.com
SMTP_USER=codenikin@gmail.com
SMTP_PASS=abfp nucn anpv yrga
STRIPE_SECRET_KEY=sk_test_51XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51Hxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
STRIPE_WEBHOOKS_SIGNING_SECRET=whsec_
PAYLOAD_ENABLE_JOB_QUEUE=true
WHATSAPP_API_KEY=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY
AUTH0_DOMAIN=your_domain
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_secret
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=
NEXT_PUBLIC_RAZORPAY_PUBLISHABLE_KEY=
RAZORPAY_SECRET_KEY=

Security: Never share your production .env file or commit it to a public Git repository.

Start Payload CMS

Start the development server:
Terminal window
```
pnpm dev
```
The application will normally run on:
```
http://localhost:3000
```
Create Your Admin Account

Open the Payload CMS admin panel:
```
http://localhost:3000/admin
```
You will be presented with the Payload CMS account creation screen.

Create your administrator account.

Important: The first user created during the initial setup should be treated as the primary administrator and will have full access according to the application’s access configuration.

Success
Your local Payload CMS installation is now ready.
Seed the Database

After creating the first admin account, run the project’s database seed functionality from the application as provided by the project.

Seeding will populate the required initial website data such as:
- Homepage content
- Categories
- Products
- Brands
- Other required demo/initial data
Make sure your database connection is correctly configured in .env before running the seed.
Your Website Is Ready

After completing the above steps, your Payload CMS ecommerce website should be ready.

Important URLs

Purpose URL

Website http://localhost:3000

Admin Panel http://localhost:3000/admin

You can now log in to the admin panel and start managing your website.

Purpose	URL
Website	http://localhost:3000
Admin Panel	http://localhost:3000/admin

Before Production

Once you have finished testing the template, we recommend replacing the demo content with your own:

Logo
Favicon
Products
Brands
Categories
Images
Pages
Store information
Admin users

Important: Review and remove unnecessary demo data before launching your production website.

VPS Installation — Docker

Docker is the recommended VPS installation method if you want an isolated and easy-to-manage production environment.

License Notice: Docker deployment availability may depend on the license included with your purchase. Please check the license terms of your template. If your Docker deployment requires an extended license, contact our support team before deployment.

Prerequisites

You will need:

A VPS
Docker
Docker Compose
PostgreSQL
A domain name
SSL/HTTPS

Some VPS providers offer Docker as a one-click application. If available, this is the easiest way to prepare your server.

Installing Payload CMS with Docker

Create Your VPS

Create a VPS using your preferred hosting provider.

If your provider offers a Docker one-click installation, select the Docker image when creating the server.
Connect to Your VPS

Connect using SSH:
Terminal window
```
ssh root@your-server-ip
```
Upload the Template

Upload the template ZIP file:
Terminal window
```
scp ecommerce.zip root@your-server-ip:/var/www/
```
Extract the Project

Navigate to the project directory:
Terminal window
```
cd /var/www
```
Extract the ZIP file:
Terminal window
```
sudo unzip ecommerce.zip -d ecommerce
```
Navigate to the Project
Terminal window
```
cd /var/www/ecommerce
```

Configure the Environment

Create your production .env file and add your database and application configuration.

Example:

DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/ecomnew71
PAYLOAD_SECRET=091838d33373e774atyty
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
PAYLOAD_PUBLIC_SERVER_URL =http://localhost:3000
SERVER_URL=https://payloadecommerce.codenik.in
SMTP_HOST=smtp.gmail.com
SMTP_USER=codenikin@gmail.com
SMTP_PASS=abfp nucn anpv yrga
STRIPE_SECRET_KEY=sk_test_51XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51Hxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
STRIPE_WEBHOOKS_SIGNING_SECRET=whsec_
PAYLOAD_ENABLE_JOB_QUEUE=true
WHATSAPP_API_KEY=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY
AUTH0_DOMAIN=your_domain
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_secret
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=
NEXT_PUBLIC_RAZORPAY_PUBLISHABLE_KEY=
RAZORPAY_SECRET_KEY=

Add any additional environment variables required by your template.

Review the Dockerfile

The Dockerfile should build the application and expose the application port.

A typical configuration may look like:

FROM node:20-alpine AS base
RUN npm install -g pnpm@10
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
FROM base AS source
COPY . .
FROM source AS builder
ENV NODE_ENV=production
ENV NEXT_PUBLIC_SERVER_URL=http://localhost:3000
RUN pnpm build
FROM source AS migration
ENV NODE_ENV=production
CMD ["pnpm", "run", "payload:migrate"]
FROM node:20-alpine AS prod
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3005
ENV HOSTNAME=0.0.0.0
ENV PAYLOAD_DISABLE_DB_PUSH=true
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
COPY --from=builder /app/hero-media ./hero-media
COPY --from=builder /app/product-media ./product-media
COPY --from=builder /app/banner-media ./banner-media
COPY --from=builder /app/media ./media
COPY --from=builder /app/docker-entrypoint.sh ./docker-entrypoint.sh
RUN chmod +x ./docker-entrypoint.sh
EXPOSE 3005
CMD ["./docker-entrypoint.sh"]

Note: Your actual Dockerfile may differ depending on the template version and project architecture. Use the Dockerfile included with your purchased package whenever possible.

Configure Docker Compose

Open the docker-compose.yml file in the project root.

A typical production configuration may look like:

services:
  ecommerce:
    build: .
    container_name: payload_ecommerce
    restart: unless-stopped

    ports:
      - "3000:3000"

    environment:
      NODE_ENV: production
      PAYLOAD_SECRET: your_secure_secret
      DATABASE_URL: postgres://postgres:postgres@db:5432/ecommerce
      NEXT_PUBLIC_SERVER_URL: https://yourdomain.com

    depends_on:
      db:
        condition: service_healthy

    volumes:
      - ./public/uploads:/app/public/uploads

    networks:
      - default-net

  db:
    image: postgres:16
    container_name: payload_db
    restart: unless-stopped

    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: ecommerce

    volumes:
      - postgres_data:/var/lib/postgresql/data

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

    networks:
      - default-net

volumes:
  postgres_data:

networks:
  default-net:

Important: Replace the example passwords and secrets with secure production values.

Build and Start the Containers

Run:
Terminal window
```
sudo docker compose up -d --build
```
Docker will build the application image and start the required containers.
Verify the Containers

Check the running containers:
Terminal window
```
sudo docker ps
```
You should see your application and PostgreSQL containers running.

You can also check the Docker Compose status:
Terminal window
```
sudo docker compose ps
```
View Application Logs

If you experience any issues, check the application logs:
Terminal window
```
sudo docker compose logs -f
```
To view only the application logs:
Terminal window
```
sudo docker compose logs -f ecommerce
```
Run Database Migrations

If your Docker configuration requires migrations, run the migration command provided by the template.

For example:
Terminal window
```
sudo docker compose exec ecommerce pnpm migrate
```
Note: Some template versions run migrations automatically during deployment. Follow the migration configuration included with your package.
Configure Your Domain

Point your domain’s DNS records to your VPS IP address.

Example:
```
Type: A
Name: @
Value: YOUR_SERVER_IP
```
For www:
```
Type: A
Name: www
Value: YOUR_SERVER_IP
```
Configure HTTPS

Configure your reverse proxy and SSL certificate so the application is accessible securely.

Your production website should then be available at:
```
https://yourdomain.com
```
Create Your Admin Account

Open:
```
https://yourdomain.com/admin
```
Create your first administrator account.

Note: The first account created during the initial setup should be treated as the primary administrator.

Success
Your Payload CMS ecommerce template is now running in a Dockerized production environment.

VPS Installation — Node.js

This installation method runs the Payload CMS application directly on your VPS using Node.js.

This method is recommended for users who are comfortable managing a Linux server, Node.js, PostgreSQL, Nginx, and a process manager such as PM2.

Prerequisites

Your VPS should have:

Ubuntu or another supported Linux distribution
Node.js
pnpm
PostgreSQL
Nginx
PM2
A domain name
SSL certificate

Installing Payload CMS with Node.js

Connect to Your VPS

Connect to your server using SSH:
Terminal window
```
ssh root@your-server-ip
```
Upload the Template

Upload the template ZIP file to your server.

For example:
Terminal window
```
scp ecommerce.zip root@your-server-ip:/var/www/
```
Extract the Project

Navigate to /var/www:
Terminal window
```
cd /var/www
```
Extract the ZIP file:
Terminal window
```
sudo unzip ecommerce.zip -d ecommerce
```
Navigate to the Project
Terminal window
```
cd /var/www/ecommerce
```

Configure the Environment

Create or edit the .env file:

nano .env

Add your production configuration.

Example:

NEXT_PUBLIC_SERVER_URL=https://yourdomain.com

DATABASE_URL=postgresql://myuser:mypassword@localhost:5432/my_database

PAYLOAD_SECRET=your_secure_secret

NODE_ENV=production

SMTP_HOST=smtp.example.com
SMTP_USER=your-email@example.com
SMTP_PASS=your-email-password
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOKS_SIGNING_SECRET=
WHATSAPP_API_KEY=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=
BETTER_AUTH_SECRET=
BETTER_AUTH_URL=https://yourdomain.com
NEXT_PUBLIC_RAZORPAY_PUBLISHABLE_KEY=

Security: Replace all example credentials with your own production credentials.

Install Dependencies

Run:
Terminal window
```
pnpm i
```
Make sure the installation completes successfully without errors.
Run Database Migrations

Execute the migration command:
Terminal window
```
pnpm migrate
```
Important: Make sure the PostgreSQL database is accessible before running the migrations.
Build the Application

Create the production build:
Terminal window
```
pnpm build
```
The build must complete successfully before starting the application.
Start the Application

Start the production server:
Terminal window
```
pnpm start
```
The application will normally listen on the configured application port.
Install PM2

PM2 keeps your Node.js application running in the background and automatically restarts it if the process stops.

Install PM2 globally:
Terminal window
```
npm install -g pm2
```
Start the application:
Terminal window
```
pm2 start pnpm --name "payload-ecommerce" -- start
```
Check the application status:
Terminal window
```
pm2 status
```
View application logs:
Terminal window
```
pm2 logs payload-ecommerce
```
Configure PM2 to restart automatically after a server reboot:
Terminal window
```
pm2 save
pm2 startup
```
Follow the command displayed by PM2 to complete the startup configuration.

For more information about PM2:

PM2 Documentation

Configure Nginx

Configure Nginx as a reverse proxy to forward requests from your domain to the Payload CMS application.

Example configuration:

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

    location / {
        proxy_pass http://127.0.0.1:3000;

        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        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;
    }
}

Replace yourdomain.com with your actual domain name.

Enable HTTPS

Configure an SSL certificate for your domain.

After HTTPS has been configured, your website should be available at:
```
https://yourdomain.com
```
The Payload CMS admin panel will be available at:
```
https://yourdomain.com/admin
```
Create the Admin Account

Open:
```
https://yourdomain.com/admin
```
Create your first administrator account.
Success
Your Payload CMS ecommerce application is now running on your VPS using Node.js.

VPS Deployment Using a Standalone Build

If you prefer not to install project dependencies or build the application directly on your VPS, you can create a standalone production build locally and upload the generated files to your server.

This deployment method is useful when you want to keep the VPS lightweight and perform the build process on your local development machine.

Step 1 — Install Dependencies Locally

On your local machine, open the project directory and run:

pnpm i

Make sure all dependencies are installed successfully without errors.

Step 4 — Create the Production Build

Create the production build on your local machine:

pnpm build

The build must complete successfully without errors.

If the project is configured with Next.js standalone output, the build will generate:

.next/standalone/

Inside the standalone directory you should find:

.next/standalone/server.js

Production Checklist

Before launching your ecommerce store, make sure you have completed the following:

Ready for Production

Support

If you experience any installation or configuration issues, please contact our support team.

When contacting support, please include:

Installation method (Local / Node.js / Docker)
Operating system
Node.js version
pnpm version
PostgreSQL version
Error message
Relevant logs
Screenshot of the issue, if applicable

Providing these details will help our support team diagnose the problem more quickly.

Thank you for choosing our template.

We hope you enjoy building your ecommerce store with Payload CMS.