Skip to main content

​
Installation Guide

This guide will walk you through installing EverShop on your system. Choose the installation method that best fits your needs.

Docker

Fastest way to get started

npm/npx

Quick setup with npm

Manual

Full control over installation

​
Prerequisites

Before installing EverShop, ensure you have:

Node.js 18+

Download from nodejs.org

PostgreSQL 13+

Database server for data storage
Important: EverShop requires PostgreSQL 13.0 or higher. Earlier versions are not supported and the installation will fail.

​
Docker Installation

The fastest way to get started with EverShop is using Docker. This method handles all dependencies automatically.
1

Download Docker Compose File

Download the official docker-compose.yml file:
curl -sSL https://raw.githubusercontent.com/evershopcommerce/evershop/main/docker-compose.yml > docker-compose.yml
This will create a docker-compose.yml file in your current directory.
2

Review Configuration

The Docker Compose file includes two services:
version: '3.8'

services:
  app:
    image: evershop/evershop:latest
    restart: always
    environment:
      DB_HOST: database
      DB_PORT: 5432
      DB_PASSWORD: postgres
      DB_USER: postgres
      DB_NAME: postgres
    networks:
      - myevershop
    depends_on:
      - database
    ports:
      - 3000:3000
  
  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:
The database credentials are set to default values. For production, change the POSTGRES_PASSWORD to a secure password.
3

Start Services

Launch EverShop and PostgreSQL containers:
docker compose up -d
This command will:
  • Pull the latest EverShop image
  • Pull PostgreSQL 16 image
  • Create and start both containers
  • Set up the network and volumes
4

Access Your Store

Once the containers are running, access your store:

Storefront

Visit http://localhost:3000

Admin Panel

Visit http://localhost:3000/admin
The first startup may take a few minutes while the database is initialized.

​
Docker Management Commands

# Stop all containers
docker compose stop

​
npm Installation

Install EverShop using npm for a traditional Node.js setup.
1

Install PostgreSQL

First, ensure PostgreSQL 13+ is installed and running on your system.
# Using Homebrew
brew install postgresql@16
brew services start postgresql@16
2

Create Database

Create a PostgreSQL database for EverShop:
# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE evershop;

# Exit psql
\q
3

Create Project

Use npm to create a new EverShop project:
# Create a new directory for your project
mkdir my-evershop-store
cd my-evershop-store

# Initialize with npm
npm init -y

# Install EverShop
npm install @evershop/evershop
4

Run Setup

Run the interactive setup wizard:
npm run setup
The setup wizard will prompt you for:
  • Database Host (default: localhost)
  • Database Port (default: 5432)
  • Database Name (default: evershop)
  • Database User (default: postgres)
  • Database Password
  • Admin Full Name
  • Admin Email
  • Admin Password (minimum 8 characters, must contain letters and numbers)
The setup command creates a .env file with your database configuration and initializes the database schema.
5

Build Assets

Build the frontend and backend assets:
npm run build
This process:
  • Compiles TypeScript to JavaScript
  • Bundles React components with Webpack
  • Processes and minifies CSS with Tailwind
  • Optimizes assets for production
6

Start Server

Launch the production server:
npm run start
Your store will be available at:

​
Development Mode

For development, use the dev server with hot reloading: 
npm run dev
Development mode includes hot module replacement (HMR) for faster development. Changes to React components and styles are reflected instantly without page refresh.

​
Environment Variables

After running npm run setup, a .env file is created with your configuration:
.env
DB_HOST="localhost"
DB_PORT="5432"
DB_NAME="evershop"
DB_USER="postgres"
DB_PASSWORD="your_password"
DB_SSLMODE="disable"
Never commit the .env file to version control. It contains sensitive database credentials.

​
Manual Installation

For full control over the installation process, clone the repository and build from source.
1

Clone Repository

Clone the EverShop repository:
git clone https://github.com/evershopcommerce/evershop.git
cd evershop
2

Install Dependencies

Install all required packages:
npm install
This installs dependencies for:
  • Main EverShop package
  • All workspace packages
  • Development tools
3

Setup Database

Ensure PostgreSQL is running, then run the setup:
npm run setup
Follow the interactive prompts to configure your database and create an admin user.
4

Compile TypeScript

If you’re developing or modifying core code, compile TypeScript:
npm run compile
This compiles TypeScript source files from packages/evershop/src/ to packages/evershop/dist/.
5

Build and Start

Build the application and start the server:
npm run build
npm run start

​
Development Commands

{
  "scripts": {
    "dev": "node ./packages/evershop/dist/bin/dev/index.js",
    "start": "node ./packages/evershop/dist/bin/start/index.js",
    "build": "node ./packages/evershop/dist/bin/build/index.js",
    "setup": "evershop install",
    "compile": "rimraf ./packages/evershop/dist && cd ./packages/evershop && swc ./src/ -d dist/ --config-file .swcrc --copy-files --strip-leading-paths",
    "test": "ALLOW_CONFIG_MUTATIONS=true NODE_OPTIONS=--experimental-vm-modules node_modules/jest/bin/jest.js",
    "lint": "eslint --fix --ext .js,.jsx,.ts,.tsx ./packages"
  }
}

​
Troubleshooting

​
Database Connection Issues

Ensure PostgreSQL is running:
# Check PostgreSQL status (Linux/macOS)
sudo systemctl status postgresql

# macOS with Homebrew
brew services list

# Start PostgreSQL if not running
sudo systemctl start postgresql
The installer automatically detects SSL support. If you encounter SSL errors:
  1. Check your .env file for DB_SSLMODE setting
  2. Try setting DB_SSLMODE="disable" for local development
  3. For production, ensure your PostgreSQL server has valid SSL certificates
EverShop requires PostgreSQL 13+. Check your version:
psql --version
Upgrade if necessary:
# Ubuntu/Debian
sudo apt install postgresql-16

# macOS
brew upgrade postgresql

​
Build Issues

Increase Node.js memory limit:
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build
Clear node_modules and reinstall:
rm -rf node_modules package-lock.json
npm install

​
Port Already in Use

If port 3000 is already in use, modify the port in your configuration: 
# Set custom port (before starting)
export PORT=3001
npm run start

​
Next Steps

Quick Start

Learn basic operations and workflows

Configuration

Configure your store settings

Extensions

Add functionality with extensions
Join our Discord community if you need help with installation or have questions!

Build docs developers (and LLMs) love

Get started for freeTalk to us