website/GETTING_STARTED.md

# Getting Started - EZSCALE Billing Platform Development

This guide will help you start building the EZSCALE Billing Platform on your development machine.

## Prerequisites

### Required Software
- **PHP** 8.2 or higher
- **Composer** 2.x
- **Node.js** 18.x or higher
- **npm** 9.x or higher
- **MySQL** 8.0 or higher
- **Redis** 6.x or higher
- **Git**

### Optional but Recommended
- **Laravel Herd** (all-in-one Laravel development environment)
- **TablePlus** or **MySQL Workbench** (database GUI)
- **Redis Desktop Manager** (Redis GUI)
- **Postman** or **Insomnia** (API testing)

## Step 1: Clone Repository

```bash
# Clone the repository
git clone git@github.com:EZSCALE/accounting.git ezscale_billing
cd ezscale_billing

# Create develop branch
git checkout -b develop
```

## Step 2: Initialize Laravel 12 Project

Since this is currently just documentation, you'll initialize a fresh Laravel 12 project:

```bash
# Install Laravel 12 with Vue + Inertia starter kit
composer create-project laravel/laravel .

# During installation, select:
# - Starter kit: Vue + Inertia
# - Testing framework: Pest
# - Database: MySQL
```

## Step 3: Configure Environment

```bash
# Copy the planning files (already in repo)
# .env file should already exist, update it:

APP_NAME="EZSCALE Billing"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ezscale_billing
DB_USERNAME=root
DB_PASSWORD=your_password

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Stripe keys (get from Stripe dashboard)
STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...

# PayPal credentials (get from PayPal developer dashboard)
PAYPAL_MODE=sandbox
PAYPAL_SANDBOX_CLIENT_ID=...
PAYPAL_SANDBOX_CLIENT_SECRET=...

# Email (choose Mailgun or SendGrid)
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=...
MAIL_PASSWORD=...
MAIL_FROM_ADDRESS=noreply@ezscale.cloud
MAIL_FROM_NAME="EZSCALE Hosting"

# Discord webhook for admin alerts
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
```

## Step 4: Create Database

```bash
# Connect to MySQL
mysql -u root -p

# Create database
CREATE DATABASE ezscale_billing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;
```

## Step 5: Install Dependencies

```bash
# Install PHP dependencies
composer require laravel/cashier
composer require laravel/fortify
composer require laravel/passport
composer require srmklive/laravel-paypal
composer require spatie/laravel-permission
composer require --dev laravel/telescope

# Install Node dependencies
npm install
```

## Step 6: Add Vuexy Theme

```bash
# Extract Vuexy theme source files to:
# resources/js/vuexy/
# resources/css/vuexy/

# Update vite.config.js to include Vuexy assets
# Update app.js to import Vuexy components

# Detailed integration instructions in Vuexy documentation
```

## Step 7: Run Migrations

```bash
# Generate app key
php artisan key:generate

# Run Laravel's default migrations
php artisan migrate

# Publish Cashier migrations
php artisan vendor:publish --tag="cashier-migrations"

# Publish Passport migrations
php artisan passport:install

# Publish Spatie migrations
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

# Now create your custom migrations (see PROJECT_DEVELOPMENT.md for schema)
# php artisan make:migration create_user_profiles_table
# php artisan make:migration create_plans_table
# ... etc

# Run all migrations
php artisan migrate
```

## Step 8: Seed Initial Data

```bash
# Create seeders
php artisan make:seeder RoleSeeder
php artisan make:seeder PlanSeeder
php artisan make:seeder DatacenterSeeder

# Run seeders
php artisan db:seed
```

## Step 9: Configure Authentication

```bash
# Publish Fortify views
php artisan vendor:publish --tag=fortify-views

# Install Fortify
php artisan fortify:install

# Configure Fortify features in config/fortify.php
# Enable: registration, reset passwords, email verification, two factor

# Set up Passport for OAuth2 (SSO later)
php artisan passport:install
```

## Step 10: Start Development Servers

```bash
# Terminal 1: Start Laravel server
php artisan serve

# Terminal 2: Start Vite dev server
npm run dev

# Terminal 3: Start queue worker
php artisan queue:work

# Optional Terminal 4: Start Horizon (queue monitoring)
php artisan horizon
```

## Step 11: Configure Local Domains (Optional)

If using Laravel Herd or Valet, you can set up local domains:

```bash
# With Herd/Valet
ezscale.test -> Marketing site
account.ezscale.test -> Customer dashboard
admin.ezscale.test -> Admin panel
```

Update `.env`:
```
APP_URL=http://ezscale.test
```

## Step 12: Set Up Testing

```bash
# Create test database
CREATE DATABASE ezscale_billing_test;

# Update phpunit.xml or .env.testing
DB_DATABASE=ezscale_billing_test

# Run tests
php artisan test
```

## Development Workflow

### Daily Development
```bash
# Pull latest changes
git pull origin develop

# Install any new dependencies
composer install
npm install

# Run migrations
php artisan migrate

# Start dev servers
php artisan serve
npm run dev
php artisan queue:work
```

### Creating Features
```bash
# Create feature branch from develop
git checkout develop
git pull
git checkout -b feature/billing-system

# Make changes, commit often
git add .
git commit -m "Add Stripe billing service"

# Push to remote
git push origin feature/billing-system

# Create PR on GitHub: feature/billing-system -> develop
```

### Running Tests
```bash
# Run all tests
php artisan test

# Run specific test
php artisan test --filter BillingServiceTest

# Run with coverage
php artisan test --coverage
```

## Phase 1 Checklist

Use this checklist to track Phase 1 Foundation progress:

- [ ] Laravel 12 project initialized
- [ ] Vuexy theme integrated
- [ ] Environment configured (.env)
- [ ] Database created and connected
- [ ] All dependencies installed (Cashier, Fortify, Passport, PayPal, Spatie)
- [ ] Custom migrations created (see PROJECT_DEVELOPMENT.md for full schema)
  - [ ] user_profiles
  - [ ] plans
  - [ ] datacenters
  - [ ] payment_transactions
  - [ ] services
  - [ ] provisioning_logs
  - [ ] bandwidth_usage
  - [ ] audit_logs
  - [ ] support_tickets (mirror)
  - [ ] announcements
- [ ] Migrations run successfully
- [ ] Seeders created and run
- [ ] Fortify authentication configured
- [ ] Passport OAuth2 set up
- [ ] Spatie roles configured (admin, customer)
- [ ] Redis working
- [ ] Queue working
- [ ] Email sending working (test with Mailtrap initially)
- [ ] Git repository initialized
- [ ] CI/CD pipeline set up (GitHub Actions)
- [ ] Staging environment created

## Common Issues & Solutions

### Issue: Composer dependencies conflict
**Solution**: Check PHP version (must be 8.2+), update composer.json constraints

### Issue: npm install fails
**Solution**: Delete node_modules and package-lock.json, run `npm install` again

### Issue: Database connection refused
**Solution**: Check MySQL is running, verify credentials in .env

### Issue: Redis connection failed
**Solution**: Start Redis server: `redis-server` or check if running with `redis-cli ping`

### Issue: Vite not compiling
**Solution**: Clear Vite cache: `npm run build`, restart `npm run dev`

### Issue: Queue jobs not processing
**Solution**: Ensure `php artisan queue:work` is running, check Redis connection

## API Credentials You'll Need

Before full development, obtain these API credentials:

### Payment Gateways
- [ ] Stripe test keys (pk_test_, sk_test_)
- [ ] Stripe production keys (pk_live_, sk_live_)
- [ ] PayPal sandbox credentials
- [ ] PayPal production credentials

### Provisioning APIs
- [ ] VirtFusion API key
- [ ] Pterodactyl API token
- [ ] SynergyCP API credentials
- [ ] Enhance API key

### External Services
- [ ] SupportPal API credentials
- [ ] ElastiFlow API access
- [ ] Mailgun or SendGrid API key
- [ ] Discord webhook URL
- [ ] Twilio credentials (for SMS alerts - optional)
- [ ] Cloudflare API token (for DNS integration)
- [ ] Coinbase Commerce API (for crypto payments - optional)

### Development Tools
- [ ] GitHub personal access token (for Actions)
- [ ] Sentry DSN (for error tracking - optional)

## Documentation Reference

As you build, refer to these files:

| File | When to Reference |
|------|-------------------|
| **PROJECT_DEVELOPMENT.md** | Architecture decisions, database schema, API integrations |
| **TASKS.md** | Task checklist, what to build in each phase |
| **FEATURES.md** | Detailed feature specifications, implementation notes |
| **CLAUDE.md** | Code conventions, security requirements |

## Next Steps After Phase 1

Once Phase 1 is complete:
1. Review Phase 1 deliverables
2. Demo authentication flow
3. Verify all integrations are working (test API connections)
4. Begin Phase 2: Billing & Subscriptions

## Getting Help

- **Laravel Documentation**: https://laravel.com/docs/12.x
- **Vuexy Documentation**: Check included docs in theme package
- **Cashier Documentation**: https://laravel.com/docs/12.x/billing
- **Project Planning Docs**: See CLAUDE.md, PROJECT_DEVELOPMENT.md, FEATURES.md

## Development Team

Add team member contact information here as project progresses.

---

**Ready to build?** Start with Phase 1 tasks from TASKS.md!