Skip to content

Run from Source

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

Below are the instructions to run wexCommerce from code.

Prerequisites

  1. Install git, Node.js, NGINX or IIS, MongoDB and mongosh. If you want to use MongoDB Atlas, you can skip installing and configuring MongoDB.

  2. Configure MongoDB:

mongosh

Create admin user:

db = db.getSiblingDB('admin')
db.createUser({ user: "admin", pwd: "PASSWORD", roles:["root"]})

Replace PASSWORD with a strong password.

Secure MongoDB by changing mongod.conf as follows:

net:
  port: 27017
  bindIp: 0.0.0.0

security:
  authorization: enabled

Restart MongoDB service.

Instructions

  1. Clone wexCommerce repo:
sudo git clone https://github.com/aelassas/wexcommerce.git
  1. Add backend/.env file:
# General
NODE_ENV=development

# 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://127.0.0.1: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:8005/
WC_FRONTEND_HOST=http://localhost:8006/
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 it secret)
WC_SENTRY_TRACES_SAMPLE_RATE=1.0 # Tracing sample rate: 1.0 = 100%, 0.1 = 10%, 0 = disabled

You must configure the following options:

WC_DB_URI=mongodb://127.0.0.1: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_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
WC_WEBSITE_NAME=wexCommerce

On Windows, create C:\inetpub\wwwroot\cdn folder and add full access right to current user then update the following settings with these values:

WC_CDN_ROOT=C:\inetpub\wwwroot\cdn
WC_CDN_USERS=C:\inetpub\wwwroot\cdn\wexcommerce\users
WC_CDN_TEMP_USERS=C:\inetpub\wwwroot\cdn\wexcommerce\temp\users
WC_CDN_CATEGORIES=C:\inetpub\wwwroot\cdn\wexcommerce\categories
WC_CDN_TEMP_CATEGORIES=C:\inetpub\wwwroot\cdn\wexcommerce\temp\categories
WC_CDN_PRODUCTS=C:\inetpub\wwwroot\cdn\wexcommerce\products
WC_CDN_TEMP_PRODUCTS=C:\inetpub\wwwroot\cdn\wexcommerce\temp\products

If you want to use MongoDB Atlas, put you MongoDB Atlas URI in WC_DB_URI otherwise replace PASSWORD in WC_DB_URI with your MongoDB password. Replace JWT_SECRET with a secret token. Finally, set the SMTP options. SMTP options are necessary for sign up. You can use sendgrid or any other transactional email provider.

If you choose sendgrid, create an account on sendgrid.com, login and go to the dashboard. On the left panel, click on Email API, then on Integration Guide. Then, choose SMTP Relay and follow the steps. You will be prompted to create an API Key. Once you create the API Key and verify the smtp relay, copy the API key in WC_SMTP_PASS in ./api/.env. Sendgrid's free plan allows to send up to 100 emails/day. If you need to send more than 100 emails/day, switch to a paid plan or choose another transactional email provider.

COOKIE_SECRET and JWT_SECRET should at least be 32 characters long, but the longer the better. You can use an online password generator and set the password length to 32 or longer.

To enable stripe payment gateway, sign up for a stripe account, fill the forms and save the publishable key and the secret key from stripe dashboard. Then, set the secret key in the following option in api/.env:

WC_STRIPE_SECRET_KEY=STRIPE_SECRET_KEY

Don't expose stripe secret key on a website or embed it in a mobile application. It must be secret and stored securely in the server-side. Use stripe in test mode.

Use only your test API keys for testing. This ensures that you don't accidentally modify your live customers or charges.

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

Run the backend server:

cd ./backend
npm install
npm run dev
  1. Add admin/.env file and set the following options:
NEXT_PUBLIC_WC_SERVER_API_HOST=http://localhost:4005
NEXT_PUBLIC_WC_CLIENT_API_HOST=http://localhost:4005
NEXT_PUBLIC_WC_PAGE_SIZE=30
NEXT_PUBLIC_WC_CDN_USERS=http://localhost:4005/cdn/wexcommerce/users
NEXT_PUBLIC_WC_CDN_TEMP_USERS=http://localhost:4005/cdn/wexcommerce/temp/users
NEXT_PUBLIC_WC_CDN_CATEGORIES=http://localhost:4005/cdn/wexcommerce/categories
NEXT_PUBLIC_WC_CDN_TEMP_CATEGORIES=http://localhost:4005/cdn/wexcommerce/temp/categories
NEXT_PUBLIC_WC_CDN_PRODUCTS=http://localhost:4005/cdn/wexcommerce/products
NEXT_PUBLIC_WC_CDN_TEMP_PRODUCTS=http://localhost:4005/cdn/wexcommerce/temp/products

Run the admin panel:

cd ./admin
npm install --force
npm run dev
  1. Add frontend/.env file:
NEXT_PUBLIC_WC_SERVER_API_HOST=http://localhost:4005
NEXT_PUBLIC_WC_CLIENT_API_HOST=http://localhost:4005
NEXT_PUBLIC_WC_PAGE_SIZE=30
NEXT_PUBLIC_WC_CDN_USERS=http://localhost:4005/cdn/wexcommerce/users
NEXT_PUBLIC_WC_CDN_CATEGORIES=http://localhost:4005/cdn/wexcommerce/categories
NEXT_PUBLIC_WC_CDN_PRODUCTS=http://localhost:4005/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

You must configure the following options:

NEXT_PUBLIC_WC_CDN_USERS=http://localhost:4005/cdn/wexcommerce/users
NEXT_PUBLIC_WC_CDN_CATEGORIES=http://localhost:4005/cdn/wexcommerce/categories
NEXT_PUBLIC_WC_CDN_PRODUCTS=http://localhost:4005/cdn/wexcommerce/products
NEXT_PUBLIC_WC_STRIPE_PUBLISHABLE_KEY=STRIPE_PUBLISHABLE_KEY

To use social login, set these options:

NEXT_PUBLIC_WC_FB_APP_ID=XXXXXXXXXX
NEXT_PUBLIC_WC_APPLE_ID=XXXXXXXXXX
NEXT_PUBLIC_WC_GG_APP_ID=XXXXXXXXXX

To enable stripe payment gateway, set stripe publishable key in NEXT_PUBLIC_WC_STRIPE_PUBLISHABLE_KEY. You can retrieve it from stripe dashboard.

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.

Run the frontend:

cd ./frontend
npm install --force
npm run dev
  1. Configure http://localhost:4005/cdn
  • On Windows, createC:\inetpub\wwwroot\cdn\bookcars folder and add full access permissions to the user who is running BookCars API on C:\inetpub\wwwroot\cdn.
  • On Linux, create /var/www/cdn folder and add full access permissions to the user who is running BookCars API on /var/www/cdn.
  1. Create an admin user from http://localhost:8005/sign-up

You can change language and currency from settings page in the backend.

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