CloudPOS Documentation

# Local Installation

This guide will help you set up CloudPOS on your local computer for development or testing.

# Step 1: Clone or Download the Project

If you have the project files, navigate to the project directory:

cd CloudPOS

# Step 2: Install Root Dependencies

Install the root package dependencies:

npm install

This installs dotenv which is used for environment variable management.

# Step 3: Create Environment File

Create a .env file in the project root:

# Windows
copy .env.example .env

# macOS/Linux
cp .env.example .env

Note: If .env.example doesn't exist, create .env manually (see Environment Configuration).

# Step 4: Configure Database

  1. Create MySQL Database

Open MySQL command line or MySQL Workbench:

CREATE DATABASE cloudpos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  1. Update .env File

Edit the .env file in the project root and set your database connection:

DATABASE_URL="mysql://root:@localhost:3306/cloudpos"

For Laragon (Windows):

DATABASE_URL="mysql://root:@localhost:3306/cloudpos"

For MySQL with password:

DATABASE_URL="mysql://root:yourpassword@localhost:3306/cloudpos"

For custom user:

DATABASE_URL="mysql://cloudpos:yourpassword@localhost:3306/cloudpos"

# Step 5: Setup Backend (Server)

  1. Navigate to server directory:
cd server
  1. Install dependencies:
npm install
  1. Generate Prisma Client:
npm run prisma:generate

This creates the database client based on the Prisma schema.

  1. Run database migrations:
npm run prisma:migrate

This creates all database tables. You may be prompted to name the migration - just press Enter to use the default.

  1. Seed the database (optional):

This creates sample data for testing:

npm run prisma:seed

Default test credentials:

  • Email: admin@acme.com
  • Password: password123
  1. Create admin user (for SaaS admin panel):
npm run prisma:seed:cms

Or manually:

npx ts-node prisma/create-admin.ts

Default admin credentials:

  • Email: admin@cloudpos.com
  • Password: admin123

⚠️ Important: Change these passwords after first login!

  1. Start the development server:
npm run start:dev

The API server will start at http://localhost:3000/api

Verify it's working:

  • Open: http://localhost:3000/api/health (if health endpoint exists)
  • You should see the server logs in the terminal

# Step 6: Setup Frontend (Client)

Open a new terminal window (keep the server running):

  1. Navigate to client directory:
cd client
  1. Install dependencies:
npm install
  1. Start the development server:
npm run dev

The frontend will start at http://localhost:5173

# Step 7: Verify Installation

# Check Backend API

Open your browser and visit:

http://localhost:3000/api

You should see a response (may be an error page, but the server is running).

# Check Frontend

Open your browser and visit:

http://localhost:5173

You should see the CloudPOS landing page or login page.

# Test Login

  1. Login as Tenant User:

    • Go to: http://localhost:5173/login
    • Email: admin@acme.com
    • Password: password123

  2. Login as Admin:

    • Go to: http://localhost:5173/admin/login
    • Email: admin@cloudpos.com
    • Password: admin123

# Step 8: Common Development Commands

# Backend (in server/ directory)

# Start development server (with hot reload)
npm run start:dev

# Build for production
npm run build

# Start production server
npm run start:prod

# Run database migrations
npm run prisma:migrate

# Generate Prisma Client (after schema changes)
npm run prisma:generate

# Open Prisma Studio (database GUI)
npm run prisma:studio

# Seed database
npm run prisma:seed

# Frontend (in client/ directory)

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

# Fix linting errors
npm run lint:fix

# Troubleshooting

# Database Connection Error

Error: Can't reach database server or Authentication failed

Solutions:

  1. Check MySQL is running:

    # Windows (Laragon)
# Check Laragon dashboard - MySQL should be green

# macOS
brew services list

# Linux
sudo systemctl status mysql

  2. Verify database exists:

    SHOW DATABASES;
-- Should see 'cloudpos' in the list

  3. Check credentials in .env:

    • Make sure DATABASE_URL is correct
    • Test connection: mysql -u root -p -h localhost

# Port Already in Use

Error: Port 3000 is already in use

Solution:

  1. Find the process:

    # Windows
netstat -ano | findstr :3000

# macOS/Linux
lsof -i :3000

  2. Kill the process or change port:

    • Edit .env: PORT=3001
    • Update CORS_ORIGIN and FRONTEND_URL accordingly

# Prisma Migration Errors

Error: Migration failed or Table already exists

Solutions:

  1. Reset database (⚠️ deletes all data):

    cd server
npx prisma migrate reset
npm run prisma:generate
npm run prisma:migrate

  2. Or push schema without migrations:

    npm run prisma:db:push

# Frontend Can't Connect to API

Error: Network Error or CORS error

Solutions:

  1. Check API server is running:

    • Visit: http://localhost:3000/api
    • Should see a response

  2. Check CORS settings in .env:

    CORS_ORIGIN=http://localhost:5173

  3. Restart both servers:

    • Stop both servers (Ctrl+C)
    • Start backend first, then frontend

# Next Steps

Now that you have CloudPOS running locally:

  1. ✅ Configure Environment Variables - See Environment Configuration
  2. ✅ Set up Admin Panel - See Admin Panel
  3. ✅ Configure Payment Gateway - See Payment Gateway (optional)
  4. ✅ Set up Email - See Email Notifications (optional)

Ready for production? See Production Installation

← Production Installation →