CloudPOS Documentation

# System Requirements

Before installing CloudPOS, ensure your system meets the following requirements.

# Server Specifications

# Minimum Requirements (Development)

  • CPU: 2 cores
  • RAM: 4 GB
  • Storage: 10 GB free space
  • OS: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+)
  • CPU: 4+ cores
  • RAM: 8+ GB
  • Storage: 50+ GB SSD
  • OS: Linux (Ubuntu 22.04 LTS or similar)

# Required Software

# 1. Node.js

  • Version: Node.js 18 or higher
  • Check version: node --version
  • Download: https://nodejs.org/

Installation:

# Windows (using installer)
# Download from nodejs.org and run installer

# macOS (using Homebrew)
brew install node@18

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. npm or yarn

  • npm comes with Node.js (check: npm --version)
  • yarn (optional): npm install -g yarn

# 3. MySQL Database

  • Version: MySQL 8.0 or higher
  • Alternative: MariaDB 10.5+

Installation:

# Windows (using Laragon/XAMPP/WAMP)
# Download Laragon from https://laragon.org/

# macOS (using Homebrew)
brew install mysql@8.0
brew services start mysql@8.0

# Linux (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql

Verify MySQL is running:

# Windows (Laragon)
# Check Laragon dashboard

# macOS/Linux
mysql --version
# Or check service status
sudo systemctl status mysql  # Linux
brew services list           # macOS

# 4. Git (Optional)

  • Version: Any recent version
  • Download: https://git-scm.com/

# Required Ports

Make sure these ports are available:

Port Service Description
3000 API Server Backend API (NestJS)
5173 Client/Admin Frontend (Vite dev server)
3306 MySQL Database (default)

Check if ports are in use:

# Windows
netstat -ano | findstr :3000
netstat -ano | findstr :5173
netstat -ano | findstr :3306

# macOS/Linux
lsof -i :3000
lsof -i :5173
lsof -i :3306

# Domain Requirements (Production)

For production deployment, you'll need:

# Option 1: Single Domain

  • Domain: yourdomain.com
  • API: https://yourdomain.com/api
  • Client: https://yourdomain.com (served by API server)
  • Admin: https://yourdomain.com/admin
  • API: https://api.yourdomain.com
  • Client: https://app.yourdomain.com
  • Admin: https://admin.yourdomain.com

# SSL Certificate

  • Required: Yes (HTTPS)
  • Options:
    • Let's Encrypt (free)
    • Cloudflare SSL
    • Commercial SSL certificate

# Optional Services

# Redis (Optional - for caching)

  • Version: Redis 6.0+
  • Purpose: Session storage, caching (not required for basic setup)

# PM2 (Production Process Manager)

  • Installation: npm install -g pm2
  • Purpose: Keep Node.js processes running in production

# Nginx (Production Web Server)

  • Version: Nginx 1.18+
  • Purpose: Reverse proxy, SSL termination, static file serving

# Development Tools (Optional)

  • VS Code or any code editor
  • Postman or Insomnia for API testing
  • MySQL Workbench or phpMyAdmin for database management

# Browser Requirements

# Supported Browsers

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

# Quick Check Script

Run these commands to verify your setup:

# Check Node.js
node --version
# Should show: v18.x.x or higher

# Check npm
npm --version
# Should show: 9.x.x or higher

# Check MySQL
mysql --version
# Should show: mysql Ver 8.0.x or higher

# Check Git (optional)
git --version

# Common Issues

# Node.js Version Too Old

Error: Error: Node.js version X is not supported

Solution: Update Node.js to version 18 or higher

# MySQL Not Running

Error: ECONNREFUSED or Can't connect to MySQL server

Solution:

  • Windows (Laragon): Start MySQL from Laragon dashboard
  • macOS: brew services start mysql@8.0
  • Linux: sudo systemctl start mysql

# Port Already in Use

Error: Port 3000 is already in use

Solution:

  • Find the process: lsof -i :3000 (macOS/Linux) or netstat -ano | findstr :3000 (Windows)
  • Kill the process or change the port in .env

# Next Steps

Once all requirements are met:

  1. ✅ Node.js 18+ installed
  2. ✅ npm installed
  3. ✅ MySQL 8+ installed and running
  4. ✅ Ports 3000, 5173, 3306 available

Proceed to: Local Installation or Production Installation

← Local Installation →