Quick Start Guide

Prerequisites (Verified)

Before you begin, ensure you have the following installed:

• Node.js: 18+ (verified: v20.19.2)
• npm: 8+ (verified: v9.2.0)
• Git: For version control
• PostgreSQL: 15+ (optional for development)
• Redis: 7+ (optional for development)

Check Your Versions

Verify your installation with these commands:

node --version    # Should return v18.0.0+
npm --version     # Should return 8.0.0+
git --version     # Should show git version

Method 1: Manual Setup (Recommended)

This method gives you full control over the setup process and is ideal for development.

Step 1: Clone Repository

# Clone the repository
git clone https://github.com/AutoBotSolutions/Opensource-Hosting-Developers-Platform.git
cd hostingco-system

Step 2: Install Dependencies

# Install all dependencies for all packages
npm run install:all

# This installs dependencies for:
# - Root package (concurrently, etc.)
# - Backend package
# - Frontend package  
# - Shared package

Step 3: Environment Configuration

# Copy environment template
cp .env.example .env

# Edit configuration (optional for development)
nano .env

Step 4: Build and Start

# Build all packages
npm run build

# Start development servers
npm run dev

# Or start individually:
npm run dev:backend    # Backend on port 3003
npm run dev:frontend   # Frontend on port 3000

Method 2: Docker Setup

If you prefer using Docker for containerized deployment:

Step 1: Clone and Setup

git clone https://github.com/AutoBotSolutions/Opensource-Hosting-Developers-Platform.git
cd hostingco-system
cp .env.example .env

Step 2: Docker Build and Run

# Build and start all services
docker-compose up -d --build

# Check logs
docker-compose logs -f

Step 3: Verify Services

# Check container status
docker-compose ps

# Access services
# Frontend: http://localhost:3000
# Backend: http://localhost:3003

Verification

Once the services are running, verify everything is working correctly:

Check System Status

# Check if services are running
curl http://localhost:3003/api/health
curl http://localhost:3000

# Check processes
ps aux | grep -E "(node|vite)" | grep -v grep

# Test API endpoints
curl http://localhost:3003/api/hosting/plans

Expected Output

Health check should return:

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2026-05-08T03:52:58.868Z",
    "uptime": 571.586811102,
    "environment": "development"
  }
}

Access Points

Once running, you can access the system at these URLs:

Default Login Credentials

For testing purposes, use these default credentials:

Project Structure

Understanding the project structure helps with navigation and development:

HostingCo/
├── backend/          # Node.js API (port 3003)
├── frontend/         # React SPA (port 3000)
├── shared/           # TypeScript types
├── data/             # Seed data & config
├── scripts/          # Automation scripts
├── docs/             # Documentation
└── logs/             # Application logs

Key Directories

• backend/ - Node.js/Express API server
• frontend/ - React single-page application
• shared/ - TypeScript types and utilities
• data/ - Seed data, configuration, and migrations
• scripts/ - Automation and utility scripts
• docs/ - Comprehensive documentation

Common Commands

Here are the most commonly used commands during development:

Development

npm run dev              # Start both servers
npm run dev:backend      # Backend only
npm run dev:frontend     # Frontend only

Building

npm run build            # Build all packages
npm run build:backend    # Backend compilation
npm run build:frontend   # Frontend build

Testing

npm run test             # Run all tests
npm run test:backend     # Backend tests
npm run test:frontend    # Frontend tests

Production

npm start                # Start production server

Troubleshooting

Common issues and their solutions:

Services Already Running

If you get "port already in use" errors:

# Check current status
curl http://localhost:3003/api/health

# If restart needed
pkill -f "npm run dev"
npm run dev

Authentication Issues

If you get 401 errors for protected endpoints:

# Get auth token
curl -X POST http://localhost:3003/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@hostingco.com","password":"admin123"}'

Port Conflicts

# Check port usage
lsof -i :3000  # Frontend
lsof -i :3003  # Backend

# Kill processes if needed
sudo fuser -k 3000/tcp
sudo fuser -k 3003/tcp

Missing Dependencies

# Install all dependencies
npm run install:all

# Build shared packages first
cd shared && npm run build && cd ..

Next Steps

Now that you have HostingCo running, here's what you can do next: