Deploying EverShop E-commerce Platform

EverShop is a modern, TypeScript-first e-commerce platform built with GraphQL and React. Designed for developers who want complete control over their online store, EverShop combines a powerful Node.js backend with a flexible React frontend, offering a modular architecture that makes it easy to customize every aspect of your e-commerce experience.

EverShop delivers essential commerce features through a clean, extensible codebase that prioritizes developer experience. Whether you’re building a boutique shop or a full-scale marketplace, EverShop provides the foundation you need with modern technologies like GraphQL APIs, server-side rendering, and a comprehensive extension system.

This guide provides a complete walkthrough for deploying EverShop on Klutch.sh using Docker, including PostgreSQL database setup, persistent volume configuration, environment management, and production-ready best practices.

Why Deploy EverShop on Klutch.sh

Instant Deployment - Push your EverShop Docker configuration to GitHub and deploy in minutes
Persistent Storage - Attach volumes for uploaded product images, media files, and user content
PostgreSQL Integration - Connect to managed PostgreSQL databases with TCP routing on port 8000
HTTP Routing - Built-in load balancing and SSL termination for your storefront and admin panel
Environment Management - Secure environment variable configuration for database credentials, API keys, and secrets
Custom Domains - Add your branded domain to your EverShop store with automatic HTTPS
Zero Downtime Deployments - Rolling updates keep your store online during deployments
Scalable Architecture - Handle traffic spikes during sales events and seasonal shopping
Developer-Friendly - GitOps workflow with automatic builds from your repository
Cost-Effective - No need to manage servers, databases, or infrastructure

Prerequisites

Before deploying EverShop on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your EverShop project
A PostgreSQL database deployed on Klutch.sh or accessible via TCP connection
Basic knowledge of Node.js, React, and e-commerce concepts
Familiarity with environment variables and Docker

What is EverShop?

EverShop is a GraphQL-based e-commerce platform that gives developers complete freedom to build tailored shopping experiences. Built from the ground up with TypeScript, React, and Node.js, it offers a modern alternative to traditional e-commerce platforms like Magento or WooCommerce.

Key Features:

TypeScript-First Architecture - Type-safe codebase for better code quality and developer experience
GraphQL API - Modern, flexible API for frontend-backend communication
React Frontend - Server-side rendered React components for fast page loads and SEO
Modular Extension System - Extend functionality without modifying core code
Theme Development - Create custom themes with complete design control
Admin Panel - Comprehensive dashboard for managing products, orders, and customers
Product Management - Categories, variants, attributes, and inventory tracking
Order Processing - Complete checkout flow with multiple payment gateway support
Customer Management - User accounts, wishlists, order history, and reviews
SEO Optimized - Built-in SEO features including meta tags, sitemaps, and structured data
Multi-Currency Support - Sell internationally with currency conversion
Shipping Integration - Flexible shipping methods and rate calculation
Tax Management - Configure tax rules based on location and product type
Responsive Design - Mobile-first approach for seamless shopping on any device
Performance Focused - Optimized for speed with caching and efficient database queries

Technology Stack:

Backend: Node.js, Express.js, TypeScript
Frontend: React, Server-Side Rendering (SSR)
API: GraphQL with Apollo
Database: PostgreSQL (or MySQL)
Build System: Webpack, Babel
Package Manager: npm

Understanding EverShop Architecture

EverShop’s architecture is built around modularity and extensibility:

Core Modules

EverShop includes essential commerce modules out of the box:

Catalog - Product listings, categories, search, and filtering
Checkout - Shopping cart, payment processing, and order completion
Order - Order management, fulfillment, and tracking
Customer - User authentication, profiles, and account management
CMS - Content pages, widgets, and blocks
Setting - Store configuration, payment methods, shipping options

Extension System

Extensions allow you to add functionality without modifying core code:

// Example extension structure
extensions/
├── my-custom-extension/
│   ├── package.json
│   ├── bootstrap.js
│   ├── api/
│   │   └── customEndpoint/
│   │       └── route.js
│   ├── graphql/
│   │   ├── schema.graphql
│   │   └── resolvers.js
│   └── pages/
│       └── frontStore/
│           └── customPage.jsx

Theme System

Themes control your store’s visual appearance:

// Example theme structure
themes/
├── my-custom-theme/
│   ├── package.json
│   ├── pages/
│   │   ├── homepage/
│   │   ├── productPage/
│   │   └── categoryPage/
│   ├── components/
│   │   ├── header/
│   │   ├── footer/
│   │   └── productCard/
│   └── css/
│       └── styles.scss

Request Flow

Incoming Request → Express server receives HTTP request
Routing → Request matched to GraphQL API or page route
GraphQL Resolver → Query/mutation processed with database operations
React Component → Server-side rendering of React components
Response → HTML sent to client with hydration scripts
Client Hydration → React takes over for interactive features

Preparing Your EverShop Repository

Step 1: Create Your Project Directory

Create a new directory for your EverShop deployment:

mkdir my-evershop-store
cd my-evershop-store
git init

Step 2: Initialize EverShop Project

Create a package.json file with EverShop dependencies:

{
  "name": "my-evershop-store",
  "version": "1.0.0",
  "description": "Custom EverShop e-commerce store",
  "scripts": {
    "setup": "evershop install",
    "build": "evershop build",
    "start": "evershop start",
    "seed": "evershop seed",
    "user:create": "evershop user:create",
    "user:changePassword": "evershop user:changePassword"
  },
  "workspaces": [
    "extensions/*",
    "themes/*"
  ],
  "dependencies": {
    "@evershop/evershop": "latest"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

Step 3: Create Directory Structure

Set up the required directories for EverShop:

mkdir -p packages themes extensions public media config translations

Step 4: Create Configuration File

Create a config/default.json file with your store configuration:

{
  "system": {
    "file_storage": "local"
  },
  "shop": {
    "timezone": "America/New_York",
    "currency": "USD",
    "language": "en",
    "weightUnit": "kg"
  },
  "catalog": {
    "product": {
      "image": {
        "thumbnail": {
          "width": 200,
          "height": 200
        },
        "listing": {
          "width": 300,
          "height": 300
        },
        "single": {
          "width": 500,
          "height": 500
        }
      }
    }
  }
}

Step 5: Create Environment Template

Create a .env.example file to document required environment variables:

# Database Configuration
DB_HOST=your-postgres-app.klutch.sh
DB_PORT=8000
DB_NAME=evershop
DB_USER=evershop
DB_PASSWORD=your-secure-password

# Session Configuration
SESSION_SECRET=your-random-session-secret-key

# Store Configuration
PORT=3000
NODE_ENV=production

# Optional: Email Configuration
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASSWORD=your-email-password
SMTP_FROM=noreply@yourstore.com

# Optional: Payment Gateway (Stripe Example)
STRIPE_PUBLISHABLE_KEY=pk_live_your_key
STRIPE_SECRET_KEY=sk_live_your_key

# Optional: Cloud Storage (AWS S3)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_S3_BUCKET=your-bucket-name
AWS_S3_REGION=us-east-1

Important: Never commit actual .env files with real credentials to your repository.

Step 6: Create the Dockerfile

Create a Dockerfile in your project root for production deployment:

# Use Node.js 18 Alpine for smaller image size
FROM node:18-alpine

# Set working directory
WORKDIR /app

# Upgrade npm to version 9
RUN npm install -g npm@9

# Copy package files for dependency installation
COPY package*.json ./

# Copy EverShop core packages
COPY packages ./packages

# Copy your custom theme (if any)
COPY themes ./themes

# Copy your custom extensions (if any)
COPY extensions ./extensions

# Copy public assets
COPY public ./public

# DO NOT copy media folder - it should be a persistent volume
# Media files will be uploaded at runtime

# Copy configuration files
COPY config ./config

# Copy translations
COPY translations ./translations

# Install all dependencies
RUN npm install

# Build the EverShop application
# This compiles TypeScript, bundles frontend assets, and prepares the app
RUN npm run build

# Expose port 3000 for HTTP traffic
EXPOSE 3000

# Health check to ensure the application is running
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/api/health', (res) => { process.exit(res.statusCode === 200 ? 0 : 1); });"

# Start the EverShop server in production mode
CMD ["npm", "run", "start"]

Step 7: Create .dockerignore

Create a .dockerignore file to exclude unnecessary files:

node_modules
.git
.github
.vscode
.DS_Store
.env
.env.*
npm-debug.log
.log/
media/
*.md
.editorconfig
.eslintrc
.prettierrc

Step 8: Create Initialization Script (Optional)

For automated setup, create a scripts/init.sh file:

#!/bin/sh

# Wait for database to be ready
echo "Waiting for PostgreSQL to be ready..."
while ! nc -z $DB_HOST $DB_PORT; do
  sleep 1
done
echo "PostgreSQL is ready!"

# Run database migrations if needed
echo "Running database setup..."
npm run setup

# Start the application
echo "Starting EverShop..."
npm run start

Make it executable:

chmod +x scripts/init.sh

Step 9: Create README

Create a README.md documenting your EverShop deployment:

# My EverShop Store

Custom e-commerce store built with EverShop and deployed on Klutch.sh.

## Requirements

- Node.js 18+
- PostgreSQL 12+
- npm 9+

## Local Development

1. Install dependencies: `npm install`
2. Configure environment: Copy `.env.example` to `.env` and fill in values
3. Run setup: `npm run setup`
4. Build assets: `npm run build`
5. Start server: `npm run start`

## Deployment

This project is configured for deployment on Klutch.sh with Docker.

## Environment Variables

See `.env.example` for required configuration.

## Extensions

Custom extensions are located in the `extensions/` directory.

## Themes

Custom themes are located in the `themes/` directory.

## License

MIT

Step 10: Push to GitHub

Initialize Git and push your EverShop project:

git add .
git commit -m "Initial EverShop deployment setup"
git branch -M main
git remote add origin https://github.com/yourusername/my-evershop-store.git
git push -u origin main

Deploying PostgreSQL Database

EverShop requires a PostgreSQL database. Deploy one on Klutch.sh first:

Follow our comprehensive PostgreSQL deployment guide to set up your database
Note your database connection details:
- Host: your-postgres-app.klutch.sh
- Port: 8000 (Klutch.sh TCP routing)
- Database Name: evershop
- Username: evershop
- Password: Your secure password
Ensure TCP traffic is enabled on port 8000 for external connections
Attach a persistent volume to /var/lib/postgresql/data for data persistence

Deploying EverShop on Klutch.sh

Log in to your Klutch.sh dashboard
Navigate to your project or create a new one by clicking "New Project"
Click "New App" to create a new application
Select GitHub as your Git source
Authorize Klutch.sh to access your GitHub repositories if you haven't already
Select your EverShop repository from the list
Choose the branch you want to deploy (typically main or master)
Klutch.sh will automatically detect your Dockerfile
Configure your app settings:
- App Name: Choose a unique name (e.g., my-evershop-store)
- Region: Select your preferred deployment region
- Traffic Type: Select HTTP (EverShop is a web application)
- Internal Port: Set to 3000 (EverShop's default port)
Add environment variables by clicking "Add Environment Variable":
- DB_HOST = your-postgres-app.klutch.sh
- DB_PORT = 8000
- DB_NAME = evershop
- DB_USER = evershop
- DB_PASSWORD = your-secure-password (mark as sensitive)
- SESSION_SECRET = your-random-session-secret (mark as sensitive)
- PORT = 3000
- NODE_ENV = production
Configure persistent storage:
- Click "Add Volume"
- Mount Path: /app/media
- Size: 10GB (adjust based on expected product images and uploads)
- This ensures uploaded product images, media files, and user content persist across deployments
Review your configuration and click "Deploy"
Klutch.sh will build your Docker image and deploy your EverShop store
Once deployed, your store will be accessible at:
- Storefront: https://your-evershop-app.klutch.sh
- Admin Panel: https://your-evershop-app.klutch.sh/admin

Initial EverShop Configuration

After your first deployment, you need to create an admin user and configure your store.

Creating Your First Admin User

In the Klutch.sh dashboard, navigate to your EverShop app
Click on "Console" or "Terminal" to access the container shell

Run the admin user creation command:

npm run user:create -- --email "admin@yourstore.com" --password "YourSecurePassword123!" --name "Admin User"

You should see a success message confirming the admin user was created
Navigate to https://your-evershop-app.klutch.sh/admin
Log in with your admin credentials

Basic Store Configuration

Once logged into the admin panel:

General Settings:
- Navigate to Settings → General
- Configure your store name, description, and contact information
- Set your store timezone, currency, and language
- Upload your store logo and favicon
Payment Methods:
- Navigate to Settings → Payment Methods
- Enable and configure payment gateways (Stripe, PayPal, etc.)
- Add payment gateway API keys as environment variables
- Test payment processing in sandbox mode first
Shipping Methods:
- Navigate to Settings → Shipping Methods
- Configure shipping zones and rates
- Set up flat rate, free shipping, or carrier-based shipping
- Define shipping restrictions and rules
Tax Configuration:
- Navigate to Settings → Tax
- Configure tax rules based on location
- Set up product-specific tax rates
- Enable/disable tax-inclusive pricing
Email Settings:
- Navigate to Settings → Email
- Configure SMTP settings for transactional emails
- Customize email templates for orders, customers, and notifications
- Test email delivery

Adding Products

Navigate to Catalog → Products in the admin panel
Click "Add New Product"
Fill in product details:
- Name: Product title
- SKU: Unique product identifier
- Price: Regular and sale price
- Description: Detailed product description
- Images: Upload product images (stored in /app/media)
- Categories: Assign to product categories
- Attributes: Define product variants (size, color, etc.)
- Inventory: Set stock quantity and tracking options
- SEO: Meta title, description, and URL key
Click "Save" to publish the product
Repeat for all your products or use bulk import features

Creating Categories

Navigate to Catalog → Categories
Click "Add New Category"
Configure category settings:
- Name: Category title
- URL Key: SEO-friendly URL slug
- Description: Category description
- Image: Category banner or thumbnail
- Parent Category: Create category hierarchy
- Status: Enable/disable category
- Meta Data: SEO meta tags
Save and assign products to categories

Demo Data Seeding (Optional)

For testing or development, you can populate your store with demo data:

# Access the container console
npm run seed

This will create sample products, categories, and customers for testing purposes.

Warning: Only use demo data seeding in development environments. Never seed demo data in production.

Using EverShop Features

Product Management

Product Variants:

Create product variations for attributes like size, color, or material:

// Example product variant structure
{
  "name": "T-Shirt",
  "sku": "TSHIRT-001",
  "variants": [
    {
      "sku": "TSHIRT-001-S-RED",
      "attributes": {
        "size": "Small",
        "color": "Red"
      },
      "price": 29.99,
      "stock": 50
    },
    {
      "sku": "TSHIRT-001-M-BLUE",
      "attributes": {
        "size": "Medium",
        "color": "Blue"
      },
      "price": 29.99,
      "stock": 75
    }
  ]
}

Inventory Tracking:

EverShop automatically tracks inventory levels and prevents overselling:

Set stock quantity for each product/variant
Enable/disable backorders
Configure low stock alerts
View inventory reports in admin panel

Product Reviews:

Enable customer reviews for products:

Navigate to Settings → Catalog → Product Reviews
Enable review functionality
Configure review moderation (auto-approve or manual)
Display star ratings on product pages

Order Management

Order Processing Workflow:

New Orders: Customer completes checkout → order created with "Pending" status
Payment Verification: Payment gateway confirms payment → order status updated to "Processing"
Fulfillment: Admin marks order as "Shipped" and adds tracking information
Delivery: Order marked as "Delivered" when customer receives package
Completion: Order marked as "Complete" after delivery confirmation

Order Management Features:

View all orders in Sales → Orders
Filter orders by status, date, customer, or amount
View detailed order information (products, shipping, payment)
Print invoices and packing slips
Add order notes and comments
Process refunds and cancellations
Send order status emails to customers

Order Notifications:

Automated email notifications are sent for:

Order confirmation
Payment received
Order shipped (with tracking)
Order delivered
Refund processed

Customer Management

Customer Accounts:

View all customers in Customers → All Customers
View customer details (orders, addresses, account info)
Manually create customer accounts
Reset customer passwords
Enable/disable customer accounts

Customer Groups:

Create customer groups for targeted pricing or promotions:

Wholesale customers
VIP members
Loyalty program tiers
Trade partners

Customer Analytics:

Track customer behavior and lifetime value:

Total orders per customer
Average order value
Customer lifetime value (CLV)
Purchase frequency
Last order date

GraphQL API Usage

EverShop provides a comprehensive GraphQL API for custom integrations.

GraphQL Endpoint:

https://your-evershop-app.klutch.sh/graphql

Example: Fetching Products

query GetProducts($filters: ProductFilterInput) {
  products(filters: $filters) {
    items {
      productId
      name
      sku
      price {
        regular
        special
      }
      image {
        url
        alt
      }
      url
      description
      qty
    }
    total
    currentPage
  }
}

Example: Creating Order (Checkout)

mutation CreateOrder($cart: CartInput!) {
  createOrder(cart: $cart) {
    orderId
    orderNumber
    status
    grandTotal
    createdAt
  }
}

Example: Customer Authentication

mutation Login($email: String!, $password: String!) {
  login(email: $email, password: $password) {
    token
    customer {
      customerId
      email
      fullName
    }
  }
}

Using GraphQL from JavaScript:

const GRAPHQL_ENDPOINT = 'https://your-evershop-app.klutch.sh/graphql';

async function fetchProducts(categoryId) {
  const query = `
    query GetProducts($categoryId: Int) {
      products(filters: { categoryId: $categoryId }) {
        items {
          productId
          name
          price {
            regular
            special
          }
          image {
            url
          }
        }
      }
    }
  `;

  const response = await fetch(GRAPHQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query,
      variables: { categoryId }
    })
  });

  const { data } = await response.json();
  return data.products.items;
}

// Usage
const products = await fetchProducts(10);
console.log(products);

Using GraphQL from Python:

import requests

GRAPHQL_ENDPOINT = 'https://your-evershop-app.klutch.sh/graphql'

def fetch_products(category_id):
    query = """
    query GetProducts($categoryId: Int) {
      products(filters: { categoryId: $categoryId }) {
        items {
          productId
          name
          price {
            regular
            special
          }
          image {
            url
          }
        }
      }
    }
    """

    response = requests.post(
        GRAPHQL_ENDPOINT,
        json={
            'query': query,
            'variables': {'categoryId': category_id}
        }
    )

    data = response.json()
    return data['data']['products']['items']

# Usage
products = fetch_products(10)
print(products)

Extension Development

Create custom extensions to add functionality to EverShop:

Extension Structure:

module.exports = {
  name: 'my-custom-extension',
  version: '1.0.0',
  description: 'Custom functionality for my store',

  // Hook into EverShop events
  async bootstrap({ app, eventBus }) {
    // Add custom middleware
    app.use('/api/custom', (req, res) => {
      res.json({ message: 'Custom API endpoint' });
    });

    // Listen to events
    eventBus.on('order.created', async (order) => {
      console.log('New order created:', order.orderNumber);
      // Add custom order processing logic
    });
  }
};

Adding GraphQL Types:

type CustomData {
  id: ID!
  value: String!
  createdAt: String!
}

extend type Query {
  customData(id: ID!): CustomData
}

extend type Mutation {
  createCustomData(value: String!): CustomData
}

GraphQL Resolvers:

module.exports = {
  Query: {
    customData: async (_, { id }, { pool }) => {
      const result = await pool.query(
        'SELECT * FROM custom_data WHERE id = $1',
        [id]
      );
      return result.rows[0];
    }
  },

  Mutation: {
    createCustomData: async (_, { value }, { pool }) => {
      const result = await pool.query(
        'INSERT INTO custom_data (value, created_at) VALUES ($1, NOW()) RETURNING *',
        [value]
      );
      return result.rows[0];
    }
  }
};

Theme Customization

Create custom themes to control your store’s appearance:

Theme Structure:

{
  "name": "my-custom-theme",
  "version": "1.0.0",
  "description": "Custom theme for my store",
  "evershop": {
    "theme": true
  }
}

Custom Homepage Component:

import React from 'react';

export default function Hero() {
  return (
    <div className="hero-section">
      <div className="hero-content">
        <h1>Welcome to Our Store</h1>
        <p>Discover amazing products at great prices</p>
        <a href="/products" className="cta-button">
          Shop Now
        </a>
      </div>
    </div>
  );
}

export const layout = {
  areaId: 'homepage.hero',
  sortOrder: 10
};

Custom Styles:

.hero-section {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  padding: 100px 20px;
  text-align: center;

  .hero-content {
    max-width: 800px;
    margin: 0 auto;

    h1 {
      font-size: 48px;
      font-weight: bold;
      margin-bottom: 20px;
    }

    p {
      font-size: 20px;
      margin-bottom: 30px;
    }

    .cta-button {
      display: inline-block;
      padding: 15px 40px;
      background: white;
      color: #667eea;
      border-radius: 30px;
      text-decoration: none;
      font-weight: bold;
      transition: transform 0.2s;

      &:hover {
        transform: scale(1.05);
      }
    }
  }
}

Override Default Components:

import React from 'react';

export default function ProductInfo({ product }) {
  return (
    <div className="product-info">
      <h1>{product.name}</h1>
      <div className="product-price">
        {product.price.special ? (
          <>
            <span className="original-price">${product.price.regular}</span>
            <span className="sale-price">${product.price.special}</span>
            <span className="discount-badge">
              Save {Math.round((1 - product.price.special / product.price.regular) * 100)}%
            </span>
          </>
        ) : (
          <span className="regular-price">${product.price.regular}</span>
        )}
      </div>
      <div className="product-description">
        {product.description}
      </div>
    </div>
  );
}

export const layout = {
  areaId: 'productPage.info',
  sortOrder: 10
};

Integrating Payment Gateways

Stripe Integration

Sign up for a Stripe account
Get your API keys from the Stripe Dashboard
Add Stripe environment variables in Klutch.sh:
- STRIPE_PUBLISHABLE_KEY = pk_live_your_key
- STRIPE_SECRET_KEY = sk_live_your_key (mark as sensitive)
Install the EverShop Stripe extension (if not built-in):
```
npm install @evershop/stripe-payment
```
Enable Stripe in admin panel:
- Navigate to Settings → Payment Methods
- Enable Stripe
- Configure display name and settings
- Test with Stripe test keys first
Test checkout flow with test card numbers from Stripe Testing Documentation

PayPal Integration

Sign up for PayPal Business
Get your API credentials from PayPal Developer Dashboard
Add PayPal environment variables:
- PAYPAL_CLIENT_ID = your_client_id
- PAYPAL_CLIENT_SECRET = your_client_secret (mark as sensitive)
- PAYPAL_MODE = live (or sandbox for testing)
Enable PayPal in admin panel and configure settings
Test with PayPal sandbox accounts before going live

Cloud Storage Integration

For production deployments, use cloud storage for product images instead of local volumes:

AWS S3 Integration

Create an AWS S3 bucket for your store media
Create an IAM user with S3 permissions and get access keys
Add AWS environment variables in Klutch.sh:
- AWS_ACCESS_KEY_ID = your_access_key
- AWS_SECRET_ACCESS_KEY = your_secret_key (mark as sensitive)
- AWS_S3_BUCKET = your-bucket-name
- AWS_S3_REGION = us-east-1
Install the EverShop S3 extension:
```
npm install @evershop/s3-file-storage
```

Update config/default.json:

{
  "system": {
    "file_storage": "s3"
  }
}

Redeploy your application
All uploaded product images will now be stored in S3

Benefits of S3:

Unlimited storage capacity
CDN integration for fast image delivery
Automatic backups and versioning
No need for persistent volumes
Better performance at scale

Azure Blob Storage Integration

Create an Azure Storage Account
Get your connection string from Azure Portal
Add Azure environment variables:
- AZURE_STORAGE_CONNECTION_STRING = your_connection_string (mark as sensitive)
- AZURE_STORAGE_CONTAINER = your-container-name

Install the Azure Blob extension:

npm install @evershop/azure-file-storage

Update configuration and redeploy

Connecting Custom Domain

To use your own domain with your EverShop store:

In the Klutch.sh dashboard, navigate to your EverShop app
Click on "Domains" or "Custom Domains"
Click "Add Domain"
Enter your domain name (e.g., shop.yourstore.com)
Klutch.sh will provide DNS records to configure:
- CNAME Record: Point your domain to Klutch.sh
- Or A Record: Point to provided IP address
Add the DNS records in your domain registrar's DNS settings
Wait for DNS propagation (usually 5-30 minutes)
Klutch.sh will automatically provision SSL certificates via Let's Encrypt
Your store will be accessible at https://shop.yourstore.com
Update your store URL in Settings → General → Store URL

Production Best Practices

Security Hardening

Environment Variable Security:

Always mark sensitive variables (passwords, API keys) as sensitive in Klutch.sh
Use strong, randomly generated passwords for database and session secrets
Rotate API keys and credentials regularly
Never commit .env files or secrets to Git repositories

Session Security:

Generate a strong session secret:

# Generate random session secret
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Use this value for SESSION_SECRET environment variable.

Admin Access:

Use strong admin passwords with letters, numbers, and special characters
Enable two-factor authentication if available
Limit admin IP addresses if possible
Regularly review admin user accounts
Log out after admin sessions

HTTPS Only:

Ensure Klutch.sh SSL/TLS is enabled (automatic)
Configure HTTPS-only cookies for sessions
Set secure headers in your configuration

Rate Limiting:

Add rate limiting to prevent abuse:

const rateLimit = require('express-rate-limit');

module.exports = {
  async bootstrap({ app }) {
    // API rate limiting
    const apiLimiter = rateLimit({
      windowMs: 15 * 60 * 1000, // 15 minutes
      max: 100, // Limit each IP to 100 requests per windowMs
      message: 'Too many requests, please try again later.'
    });

    app.use('/api/', apiLimiter);

    // Login rate limiting
    const loginLimiter = rateLimit({
      windowMs: 15 * 60 * 1000,
      max: 5, // 5 login attempts per 15 minutes
      message: 'Too many login attempts, please try again later.'
    });

    app.use('/admin/login', loginLimiter);
  }
};

Content Security Policy:

// Add CSP headers for security
app.use((req, res, next) => {
  res.setHeader(
    'Content-Security-Policy',
    "default-src 'self'; script-src 'self' 'unsafe-inline' https://js.stripe.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https://api.stripe.com"
  );
  next();
});

Performance Optimization

Database Optimization:

Add database indexes for frequently queried fields:

CREATE INDEX idx_products_sku ON products(sku);
CREATE INDEX idx_orders_customer ON orders(customer_id);
CREATE INDEX idx_orders_status ON orders(status);

Use connection pooling (built into EverShop)
Monitor slow queries and optimize them
Regularly run VACUUM and ANALYZE on PostgreSQL

Caching Strategy:

Implement Redis caching for better performance:

Deploy a Redis instance on Klutch.sh
Add Redis environment variables:
- REDIS_HOST = your-redis-app.klutch.sh
- REDIS_PORT = 8000
- REDIS_PASSWORD = your-redis-password (mark as sensitive)

Configure Redis caching in your extension:

const Redis = require('ioredis');
const redis = new Redis({
  host: process.env.REDIS_HOST,
  port: process.env.REDIS_PORT,
  password: process.env.REDIS_PASSWORD
});
// Cache product data
async function getProduct(productId) {
const cacheKey = product:${productId};
// Try cache first
const cached = await redis.get(cacheKey);
if (cached) return JSON.parse(cached);
// Fetch from database
const product = await fetchProductFromDB(productId);
// Cache for 1 hour
await redis.setex(cacheKey, 3600, JSON.stringify(product));
return product;
}

Image Optimization:

Compress product images before uploading
Use WebP format for better compression

Implement lazy loading for images:

<img src={product.image} loading="lazy" alt={product.name} />

Use responsive images with different sizes
Enable CDN for S3/Azure Blob storage

Frontend Optimization:

Minimize JavaScript bundle size
Enable Gzip compression (automatic on Klutch.sh)
Use code splitting for large components
Optimize CSS delivery
Implement service workers for offline support

Database Connection Pooling:

module.exports = {
  pool: {
    min: 2,
    max: 10,
    idle: 10000,
    acquire: 30000
  }
};

Backup and Disaster Recovery

Database Backups:

Automated Backups:
- Klutch.sh provides automatic backups for volumes
- Configure backup retention policy
- Set backup frequency (daily recommended)

Manual Backups:

# Export PostgreSQL database pg_dump -h your-postgres-app.klutch.sh -p 8000 -U evershop evershop > backup.sql Compress backup

gzip backup.sql

Restore from Backup:

# Decompress backup gunzip backup.sql.gz Restore to PostgreSQL

psql -h your-postgres-app.klutch.sh -p 8000 -U evershop evershop < backup.sql

Media File Backups:

If using local volumes:

# Backup media directory
tar -czf media-backup.tar.gz /app/media

# Upload to external storage
aws s3 cp media-backup.tar.gz s3://your-backup-bucket/

If using S3/Azure, enable versioning and lifecycle policies for automatic backups.

Configuration Backups:

Keep your EverShop configuration in Git (without secrets)
Document environment variables in .env.example
Store sensitive credentials in a secure password manager
Maintain deployment documentation

Disaster Recovery Plan:

Document recovery procedures
Test backup restoration regularly
Maintain off-site backups
Set up monitoring and alerting
Have rollback procedures ready

Monitoring and Logging

Application Monitoring:

Track application health and performance:

module.exports = {
  async bootstrap({ app }) {
    // Health check endpoint
    app.get('/api/health', (req, res) => {
      res.json({
        status: 'healthy',
        timestamp: new Date().toISOString(),
        uptime: process.uptime(),
        memory: process.memoryUsage()
      });
    });

    // Log all requests
    app.use((req, res, next) => {
      const start = Date.now();
      res.on('finish', () => {
        const duration = Date.now() - start;
        console.log({
          method: req.method,
          path: req.path,
          status: res.statusCode,
          duration: `${duration}ms`,
          timestamp: new Date().toISOString()
        });
      });
      next();
    });
  }
};

Error Tracking:

Integrate error tracking services:

// Using Sentry for error tracking
const Sentry = require('@sentry/node');

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 1.0
});

app.use(Sentry.Handlers.requestHandler());
app.use(Sentry.Handlers.errorHandler());

Database Monitoring:

Monitor PostgreSQL performance:

-- Check active connections
SELECT count(*) FROM pg_stat_activity;

-- Check slow queries
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

-- Check database size
SELECT pg_size_pretty(pg_database_size('evershop'));

-- Check table sizes
SELECT
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC
LIMIT 10;

Log Aggregation:

Use structured logging for better analysis:

const winston = require('winston');

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});

// Use logger throughout application
logger.info('Order created', {
  orderId: order.id,
  customerId: customer.id,
  total: order.grandTotal
});

Alerting:

Set up alerts for critical issues:

High error rates
Database connection failures
Slow response times
High memory usage
Failed payment processing
Inventory stockouts

Scaling Considerations

Horizontal Scaling:

Deploy multiple EverShop instances behind a load balancer
Use external session storage (Redis) for session sharing
Use cloud storage (S3/Azure) for media files
Ensure database can handle concurrent connections

Vertical Scaling:

Increase resources for your EverShop app in Klutch.sh:

More CPU for request processing
More RAM for caching and session data
Larger volumes for media storage

Database Scaling:

Use read replicas for read-heavy workloads
Implement connection pooling
Optimize queries and add indexes
Consider database sharding for very large catalogs

CDN Integration:

Use CloudFlare, AWS CloudFront, or Azure CDN
Cache static assets and product images
Reduce latency for global customers
Offload traffic from your application server

Caching Strategy:

Implement multi-layer caching:

Browser Cache: Cache static assets with long TTLs
CDN Cache: Cache pages and images at edge locations
Application Cache: Redis cache for frequently accessed data
Database Cache: PostgreSQL query cache and prepared statements

Troubleshooting Common Issues

Deployment Fails

Issue: Docker build fails during deployment

Solutions:

Check build logs in Klutch.sh dashboard
Verify Dockerfile syntax is correct
Ensure all required files are in repository
Check for missing dependencies in package.json
Verify Node.js version compatibility (18+)

Issue: Application won’t start after deployment

Solutions:

Check application logs for error messages
Verify environment variables are set correctly
Ensure PostgreSQL database is accessible
Check database credentials and connection string
Verify port 3000 is exposed and configured

Database Connection Issues

Issue: Cannot connect to PostgreSQL database

Solutions:

Verify database host, port, username, and password
Ensure database exists and user has permissions
Check if PostgreSQL is using TCP traffic on port 8000

Test connection from terminal:

psql -h your-postgres-app.klutch.sh -p 8000 -U evershop -d evershop

Check PostgreSQL logs for connection errors

Issue: Too many database connections

Solutions:

Reduce connection pool size in configuration
Check for connection leaks in custom code
Increase PostgreSQL max_connections setting
Implement connection pooling

Performance Issues

Issue: Slow page load times

Solutions:

Enable Redis caching for frequently accessed data
Optimize database queries with indexes
Use CDN for static assets and images
Compress images before uploading
Enable Gzip compression
Minimize JavaScript bundle size
Check for N+1 query problems

Issue: High memory usage

Solutions:

Reduce connection pool size
Optimize memory-intensive queries
Clear unused caches
Check for memory leaks in custom extensions
Increase container memory allocation

Admin Panel Access Issues

Issue: Cannot access admin panel

Solutions:

Verify URL is correct: https://your-app.klutch.sh/admin

Check if admin user exists:

npm run user:create -- --email "admin@example.com" --password "SecurePass123!" --name "Admin"

Clear browser cache and cookies
Check application logs for authentication errors
Verify session secret is configured

Issue: Forgot admin password

Solutions:

Reset password via terminal:

npm run user:changePassword -- --email "admin@example.com" --password "NewSecurePassword123!"

Or create a new admin user

Product Upload Issues

Issue: Cannot upload product images

Solutions:

Verify /app/media volume is attached
Check volume has sufficient space
Ensure write permissions for media directory
Check image file size limits
Verify supported image formats (JPEG, PNG, WebP)
If using S3, verify AWS credentials and bucket permissions

Issue: Uploaded images not displaying

Solutions:

Check media URL configuration in settings
Verify image files exist in /app/media or S3 bucket
Clear browser cache
Check image file permissions
Verify CDN configuration if using one

Checkout and Payment Issues

Issue: Payment gateway errors

Solutions:

Verify payment gateway credentials are correct
Check API keys are for the correct environment (live vs. sandbox)
Test with payment gateway test cards
Check payment gateway status page for outages
Review payment gateway logs for detailed errors
Ensure HTTPS is enabled (required for most gateways)

Issue: Order emails not sending

Solutions:

Verify SMTP configuration is correct

Test SMTP connection:

const nodemailer = require('nodemailer');
const transporter = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: process.env.SMTP_PORT,
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASSWORD
  }
});

transporter.verify((error, success) => {
  if (error) console.log(error);
  else console.log('SMTP ready');
});

Check email logs for errors
Verify sender email is authorized
Check spam folder

GraphQL API Issues

Issue: GraphQL queries failing

Solutions:

Test query in GraphQL Playground: https://your-app.klutch.sh/graphql
Verify query syntax is correct
Check for authentication requirements
Review GraphQL schema for available fields
Check application logs for resolver errors

Issue: CORS errors when accessing GraphQL from frontend

Solutions:

Configure CORS in EverShop:

app.use(cors({
  origin: ['https://your-frontend-domain.com'],
  credentials: true
}));

Verify allowed origins in settings
Check browser console for specific CORS errors

Additional Resources

Official Documentation

Community and Support

Extensions and Integrations

E-commerce Resources

Demo and Testing

EverShop Demo Store (demo@evershop.io / 123456)
Demo Admin Panel

Congratulations! You now have a fully functional EverShop e-commerce store running on Klutch.sh. Customize your store with themes and extensions, add products, configure payment gateways, and start selling online. For advanced features and customization, explore the EverShop documentation and join the community on Discord.

Deploying EverShop E-commerce Platform

Why Deploy EverShop on Klutch.sh

Prerequisites

What is EverShop?

Understanding EverShop Architecture

Core Modules

Extension System

Theme System

Request Flow

Preparing Your EverShop Repository

Step 1: Create Your Project Directory

Step 2: Initialize EverShop Project

Step 3: Create Directory Structure

Step 4: Create Configuration File

Step 5: Create Environment Template

Step 6: Create the Dockerfile

Step 7: Create .dockerignore

Step 8: Create Initialization Script (Optional)

Step 9: Create README

Step 10: Push to GitHub

Deploying PostgreSQL Database

Deploying EverShop on Klutch.sh

Initial EverShop Configuration

Creating Your First Admin User

Basic Store Configuration

Adding Products

Creating Categories

Demo Data Seeding (Optional)

Using EverShop Features

Product Management

Order Management

Customer Management

GraphQL API Usage

Extension Development

Theme Customization

Integrating Payment Gateways

Stripe Integration

PayPal Integration

Cloud Storage Integration

AWS S3 Integration

Azure Blob Storage Integration

Connecting Custom Domain

Production Best Practices

Security Hardening

Performance Optimization

Backup and Disaster Recovery

Compress backup

Restore to PostgreSQL

Monitoring and Logging

Scaling Considerations

Troubleshooting Common Issues

Deployment Fails

Database Connection Issues

Performance Issues

Admin Panel Access Issues

Product Upload Issues

Checkout and Payment Issues

GraphQL API Issues

Additional Resources

Official Documentation

Community and Support

Extensions and Integrations

Related Guides

E-commerce Resources

Demo and Testing