Skip to content

Installing (Docker)

Jump to bottom
Akram El Assas edited this page Jun 29, 2025 · 22 revisions

wexCommerce can run in a Docker container on Linux and Docker Desktop for Windows or Mac.

Docker Image

This section describes how to build wexCommerce Docker image and run it in a Docker container.

  1. Make sure that the ports 80, 443, 8001, 4005 and 27017 are not used by any other application on the host machine.
  2. Clone wexCommerce repo:
git clone https://github.com/aelassas/wexcommerce.git
  1. Set your MongoDB password in ./docker-compose.yml:
version: "3.8"
services:
  mongo:
    image: mongo:latest
    command: mongod --quiet --logpath /dev/null
    restart: always
    environment:
      # Provide your credentials here
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: admin
    ports:
      - 27018:27017
    volumes:
      - mongodb_data:/data/db
      - mongodb_config:/data/configdb

  mongo-express:
    image: mongo-express:latest
    restart: always
    ports:
      - 8084:8081
    environment:
      ME_CONFIG_MONGODB_URL: mongodb://admin:admin@mongo:27017/
      ME_CONFIG_BASICAUTH_USERNAME: admin
      ME_CONFIG_BASICAUTH_PASSWORD: admin
    depends_on:
      - mongo

  wc-backend:
    build:
      context: .
      dockerfile: ./backend/Dockerfile
    restart: always
    ports:
      - 4005:4005
    depends_on:
      - mongo
    volumes:
      - cdn:/var/www/cdn/wexcommerce
      - backend_logs:/wexcommerce/backend/logs

  wc-admin:
    build:
      context: .
      dockerfile: ./admin/Dockerfile
    depends_on:
      - wc-backend
    ports:
      - 8005:8005
    restart: always

  wc-nginx-admin:
    build:
      context: .
      dockerfile: ./admin/nginx/Dockerfile
    depends_on:
      - wc-admin
    ports:
      - 8001:8001
    restart: always

  wc-frontend:
    build:
      context: .
      dockerfile: ./frontend/Dockerfile
    depends_on:
      - wc-backend
    ports:
      - 8006:8006
    volumes:
      - cdn:/var/www/cdn/wexcommerce
    restart: always

  wc-nginx-frontend:
    build:
      context: .
      dockerfile: ./frontend/nginx/Dockerfile
    depends_on:
      - wc-frontend
    ports:
      - 8080:80
      - 4443:443
    volumes:
      - cdn:/var/www/cdn/wexcommerce
    restart: always

volumes:
  cdn:
  mongodb_data:
  mongodb_config:
  backend_logs:
  1. Create ./backend/.env.docker:
# General
NODE_ENV=production

# Backend server
WC_PORT=4005
WC_HTTPS=false
WC_PRIVATE_KEY=/etc/ssl/wexcommerce.key
WC_CERTIFICATE=/etc/ssl/wexcommerce.crt

# MongoDB
WC_DB_URI="mongodb://admin:admin@mongo:27017/wexcommerce?authSource=admin&appName=wexcommerce"
WC_DB_SSL=false
WC_DB_SSL_KEY=/etc/ssl/wexcommerce.key
WC_DB_SSL_CERT=/etc/ssl/wexcommerce.crt
WC_DB_SSL_CA=/etc/ssl/wexcommerce.ca.pem
WC_DB_DEBUG=false

# Auth
WC_COOKIE_SECRET=COOKIE_SECRET
WC_AUTH_COOKIE_DOMAIN=localhost
WC_ADMIN_HOST=http://localhost:8001/
WC_FRONTEND_HOST=http://localhost:8080/
WC_JWT_SECRET=JWT_SECRET
WC_JWT_EXPIRE_AT=86400
WC_TOKEN_EXPIRE_AT=86400

# Email (SMTP)
WC_SMTP_HOST=in-v3iljet.com
WC_SMTP_PORT=587
WC_SMTP_USER=USER
WC_SMTP_PASS="PASSWORD"
WC_SMTP_FROM=admin@wexcommerce.com

# CDN (File storage)
WC_CDN_ROOT=/var/www/cdn
WC_CDN_USERS=/var/www/cdn/wexcommerce/users
WC_CDN_TEMP_USERS=/var/www/cdn/wexcommerce/temp/users
WC_CDN_CATEGORIES=/var/www/cdn/wexcommerce/categories
WC_CDN_TEMP_CATEGORIES=/var/www/cdn/wexcommerce/temp/categories
WC_CDN_PRODUCTS=/var/www/cdn/wexcommerce/products
WC_CDN_TEMP_PRODUCTS=/var/www/cdn/wexcommerce/temp/products

# Localization
WC_DEFAULT_LANGUAGE=en
WC_DEFAULT_CURRENCY=\$
WC_DEFAULT_STRIPE_CURRENCY=USD

# Stripe
WC_STRIPE_SECRET_KEY=STRIPE_SECRET_KEY
WC_STRIPE_SESSION_EXPIRE_AT=82800

# PayPal
WC_PAYPAL_SANDBOX=true
WC_PAYPAL_CLIENT_ID=PAYPAL_CLIENT_ID
WC_PAYPAL_CLIENT_SECRET=PAYPAL_CLIENT_SECRET

# Admin
WC_ADMIN_EMAIL=admin@wexcommerce.com

# Google reCAPTCHA
WC_RECAPTCHA_SECRET=RECAPTCHA_SECRET

# Misc
WC_WEBSITE_NAME=wexCommerce

# IPInfo (Geo lookup)
WC_IPINFO_API_KEY=IPINFO_API_KEY # Required for more than 1000 requests/day
WC_IPINFO_DEFAULT_COUNTRY=US

# Language cleanup job
WC_BATCH_SIZE=1000 # Number of documents to process per batch when deleting obsolete language values

# Sentry (Error monitoring & performance tracing)
WC_ENABLE_SENTRY=false # Set to true to enable Sentry
WC_SENTRY_DSN_BACKEND=https://your_dsn@o0.ingest.sentry.io/your_project_id # Your backend DSN (keep this secret)
WC_SENTRY_TRACES_SAMPLE_RATE=1.0 # Tracing sample rate: 1.0 = 100%, 0.1 = 10%, 0 = disabled

Set the following settings:

WC_DB_URI=mongodb://admin:PASSWORD@mongo:27017/wexcommerce?authSource=admin&appName=wexcommerce
WC_SMTP_HOST=in-v3iljet.com
WC_SMTP_PORT=587
WC_SMTP_USER=USER
WC_SMTP_PASS=PASSWORD
WC_STRIPE_SECRET_KEY=STRIPE_SECRET_KEY
WC_WEBSITE_NAME=wexCommerce

If you want to use PayPal payment gateway instead of Stripe, you need to set:

WC_PAYPAL_CLIENT_ID=PAYPAL_CLIENT_ID
WC_PAYPAL_CLIENT_SECRET=PAYPAL_CLIENT_SECRET

If you want to test PayPal in sandbox mode, leave:

WC_PAYPAL_SANDBOX=true

If you want to test PayPal in production mode, set:

WC_PAYPAL_SANDBOX=false
  1. Create ./admin/.env.docker:
NEXT_PUBLIC_WC_SERVER_API_HOST=http://wc-backend:4005
NEXT_PUBLIC_WC_CLIENT_API_HOST=http://localhost:4005
NEXT_PUBLIC_WC_PAGE_SIZE=30
NEXT_PUBLIC_WC_CDN_USERS=http://localhost/cdn/wexcommerce/users
NEXT_PUBLIC_WC_CDN_CATEGORIES=http://localhost/cdn/wexcommerce/categories
NEXT_PUBLIC_WC_CDN_TEMP_CATEGORIES=http://localhost/cdn/wexcommerce/temp/categories
NEXT_PUBLIC_WC_CDN_PRODUCTS=http://localhost/cdn/wexcommerce/products
NEXT_PUBLIC_WC_CDN_TEMP_PRODUCTS=http://localhost/cdn/wexcommerce/temp/products
  1. Create ./frontend/.env.docker:
NEXT_PUBLIC_WC_SERVER_API_HOST=http://wc-backend:4005
NEXT_PUBLIC_WC_CLIENT_API_HOST=http://localhost:4005
NEXT_PUBLIC_WC_PAGE_SIZE=30
NEXT_PUBLIC_WC_CDN_USERS=http://localhost/cdn/wexcommerce/users
NEXT_PUBLIC_WC_CDN_CATEGORIES=http://localhost/cdn/wexcommerce/categories
NEXT_PUBLIC_WC_CDN_PRODUCTS=http://localhost/cdn/wexcommerce/products
NEXT_PUBLIC_WC_FB_APP_ID=XXXXXXXXXX
NEXT_PUBLIC_WC_APPLE_ID=XXXXXXXXXX
NEXT_PUBLIC_WC_GG_APP_ID=XXXXXXXXXX
NEXT_PUBLIC_WC_PAYMENT_GATEWAY=Stripe # Stripe or PayPal
NEXT_PUBLIC_WC_STRIPE_PUBLISHABLE_KEY=STRIPE_PUBLISHABLE_KEY
NEXT_PUBLIC_WC_PAYPAL_CLIENT_ID=PAYPAL_CLIENT_ID
NEXT_PUBLIC_WC_GOOGLE_ANALYTICS_ENABLED=false
NEXT_PUBLIC_WC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX
NEXT_PUBLIC_WC_RECAPTCHA_ENABLED=false
NEXT_PUBLIC_WC_RECAPTCHA_SITE_KEY=XXXXXXXXXX
NEXT_PUBLIC_WC_WEBSITE_NAME=wexCommerce
NEXT_PUBLIC_WC_CONTACT_EMAIL=info@wexcommerce.io

For Google Auth, you need to create OAuth 2.0 client ID and add your domains here and set NEXT_PUBLIC_WC_GG_APP_ID. Do the samething for NEXT_PUBLIC_WC_APPLE_ID here and NEXT_PUBLIC_WC_FB_APP_ID here.

If you want to use PayPal payment gateway instead of Stripe, you need to set this:

NEXT_PUBLIC_WC_PAYMENT_GATEWAY=PayPal # Stripe or PayPal
NEXT_PUBLIC_WC_PAYPAL_CLIENT_ID=PAYPAL_CLIENT_ID

You can find PayPal client id in PayPal Developer Dashboard.

  1. Run the compose:
docker compose up

If you run wexCommerce for the first time, you'll start from an empty database. An admin user is automatically created with the email provided in WC_ADMIN_EMAIL in backend/.env.docker and sh0ppingC4rt as password. Change the password once you login to the admin panel.

If you want to rebuild and run the images, run the following command:

docker compose up --build --force-recreate --no-deps wc-backend wc-admin wc-frontend

If you want to rebuild and run the images without cache, run the following command:

docker compose build --no-cache wc-backend wc-admin wc-frontend
docker compose up

Demo database

To restore the demo database, follow these instructions.

SSL

This section will walk you through how to enable SSL in the backend server, the admin panel and the frontend.

Copy your private key wexcommerce.key and your certificate wexcommerce.crt in ./.

wexcommerce.key will be loaded as /etc/ssl/wexcommerce.key and wexcommerce.crt will be loaded as /etc/ssl/wexcommerce.crt in ./docker-compose.yml.

Backend

For the backend server, update ./backend/.env.docker as follows to enable SSL:

WC_HTTPS=true
WC_PRIVATE_KEY=/etc/ssl/wexcommerce.key
WC_CERTIFICATE=/etc/ssl/wexcommerce.crt
WC_BACKEND_HOST=https://domain.com:8001/
WC_FRONTEND_HOST=https://domain.com/

Admin Panel

For the admin panel, update the following options in ./admin/.env.docker:

NEXT_PUBLIC_WC_CLIENT_API_HOST=https://domain.com:4005
NEXT_PUBLIC_WC_PAGE_SIZE=30
NEXT_PUBLIC_WC_CDN_USERS=https://domain.com/cdn/wexcommerce/users
NEXT_PUBLIC_WC_CDN_CATEGORIES=https://domain.com/cdn/wexcommerce/categories
NEXT_PUBLIC_WC_CDN_TEMP_CATEGORIES=https://domain.com/cdn/wexcommerce/temp/categories
NEXT_PUBLIC_WC_CDN_PRODUCTS=https://domain.com/cdn/wexcommerce/products
NEXT_PUBLIC_WC_CDN_TEMP_PRODUCTS=https://domain.com/cdn/wexcommerce/temp/products

Then, update ./admin/nginx/nginx.conf as follows to enable SSL:

server
{
    listen 8001 ssl;

    ssl_certificate_key /etc/ssl/wexcommerce.key;
    ssl_certificate /etc/ssl/wexcommerce.crt;

    error_page 497 301 =307 https://$host:$server_port$request_uri;

	location /
	{
		proxy_pass http://wc-admin:8005;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection 'upgrade';
		proxy_set_header Host $host:$server_port;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_set_header X-Forwarded-Host $http_host:$server_port;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_cache_bypass $http_upgrade;

		# Disable buffering for streaming support
		proxy_buffering off;
		proxy_set_header X-Accel-Buffering no;
	}
}

Frontend

For the frontend, update the following options in ./frontend/.env.docker:

NEXT_PUBLIC_WC_CLIENT_API_HOST=https://domain.com:4005
NEXT_PUBLIC_WC_PAGE_SIZE=30
NEXT_PUBLIC_WC_CDN_USERS=https://domain.com/cdn/wexcommerce/users
NEXT_PUBLIC_WC_CDN_CATEGORIES=https://domain.com/cdn/wexcommerce/categories
NEXT_PUBLIC_WC_CDN_PRODUCTS=https://domain.com/cdn/wexcommerce/products
NEXT_PUBLIC_WC_FB_APP_ID=XXXXXXXXXX
NEXT_PUBLIC_WC_APPLE_ID=XXXXXXXXXX
NEXT_PUBLIC_WC_GG_APP_ID=XXXXXXXXXX
NEXT_PUBLIC_WC_STRIPE_PUBLISHABLE_KEY=STRIPE_PUBLISHABLE_KEY
NEXT_PUBLIC_WC_GOOGLE_ANALYTICS_ENABLED=false
NEXT_PUBLIC_WC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

Then, update ./frontend/nginx.conf as follows to enable SSL:

server {
    listen 80;
    return 301 https://$host$request_uri;
}
server
{
    listen 443 ssl;

    ssl_certificate_key /etc/ssl/wexcommerce.key;
    ssl_certificate /etc/ssl/wexcommerce.crt;

	location /
	{
		proxy_pass http://wc-frontend:8006;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection 'upgrade';
		proxy_set_header Host $host:$server_port;
		proxy_set_header X-Forwarded-Proto $scheme;
		proxy_set_header X-Forwarded-Host $http_host:$server_port;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_cache_bypass $http_upgrade;

		# Disable buffering for streaming support
		proxy_buffering off;
		proxy_set_header X-Accel-Buffering no;
	}

	location /cdn
	{
		alias /var/www/cdn;
	}
}

docker-compose.yml

Update ./docker-compose.yml to load your private key wexcommerce.key and your certificate wexcommerce.crt, and add the port 443 to the frontend as follows:

version: "3.8"
services:
  mongo:
    image: mongo:latest
    command: mongod --quiet --logpath /dev/null
    restart: always
    environment:
      # Provide your credentials here
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: admin
    ports:
      - 27018:27017
    volumes:
      - mongodb_data:/data/db
      - mongodb_config:/data/configdb

  mongo-express:
    image: mongo-express:latest
    restart: always
    ports:
      - 8084:8081
    environment:
      ME_CONFIG_MONGODB_URL: mongodb://admin:admin@mongo:27017/
      ME_CONFIG_BASICAUTH_USERNAME: admin
      ME_CONFIG_BASICAUTH_PASSWORD: admin
    depends_on:
      - mongo

  wc-backend:
    build:
      context: .
      dockerfile: ./backend/Dockerfile
    restart: always
    ports:
      - 4005:4005
    depends_on:
      - mongo
    volumes:
      - cdn:/var/www/cdn/wexcommerce
      - backend_logs:/wexcommerce/backend/logs
      - ./wexcommerce.key:/etc/ssl/wexcommerce.key
      - ./wexcommerce.crt:/etc/ssl/wexcommerce.crt

  wc-admin:
    build:
      context: .
      dockerfile: ./admin/Dockerfile
    depends_on:
      - wc-backend
    ports:
      - 8005:8005
    restart: always

  wc-nginx-admin:
    build:
      context: .
      dockerfile: ./admin/nginx/Dockerfile
    depends_on:
      - wc-admin
    ports:
      - 8001:8001
    restart: always
    volumes:
      - ./wexcommerce.key:/etc/ssl/wexcommerce.key
      - ./wexcommerce.crt:/etc/ssl/wexcommerce.crt

  wc-frontend:
    build:
      context: .
      dockerfile: ./frontend/Dockerfile
    depends_on:
      - wc-backend
    ports:
      - 8006:8006
    volumes:
      - cdn:/var/www/cdn/wexcommerce
    restart: always

  wc-nginx-frontend:
    build:
      context: .
      dockerfile: ./frontend/nginx/Dockerfile
    depends_on:
      - wc-frontend
    ports:
      - 8080:80
      - 4443:443
    volumes:
      - cdn:/var/www/cdn/wexcommerce
      - ./wexcommerce.key:/etc/ssl/wexcommerce.key
      - ./wexcommerce.crt:/etc/ssl/wexcommerce.crt
    restart: always

volumes:
  cdn:
  mongodb_data:
  mongodb_config:
  backend_logs:

Rebuild and run Docker images:

docker compose up --build --force-recreate --no-deps api nginx-admin nginx-frontend

Copyright © Akram El Assas. All rights reserved.

  1. Overview
  2. Software Architecture
  3. Install Guide (Self-hosted)
  4. Install Guide (Docker)
    1. Docker Image
    2. SSL
  5. Social Login Setup Guide
  6. Free SSL Setup Guide
  7. Setup Sentry
  8. Payment Gateways
  9. Setup Stripe
  10. Run from Source
  11. Run from Source (Docker)
  12. Fork, Customize, and Sync
  13. Demo Database
    1. Windows, Linux and macOS
    2. Docker
  14. Change Language and Currency
  15. Add New Language
  16. Testing
    1. Integration Tests and Coverage
  17. Logs
  18. FAQ
  19. Release Notes
  20. Contribution Guide
  21. Code of Conduct
Clone this wiki locally