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.3 or higher
- **Composer** 2.x
- **Node.js** 24.x or higher
- **npm** 10.x or higher
- **MySQL** 8.0 or higher
- **Git**

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

## Step 1: Clone Repository

```bash
# Clone the repository
git clone git@git.ezscale.cloud:EZSCALE/website.git ezscale_billing
cd ezscale_billing
```

The Laravel 12 application is in the `website/` directory. All packages are already in `composer.json` — no separate `composer require` commands needed.

## Step 2: Navigate to Laravel Directory

```bash
# All Laravel commands run from the website/ directory
cd website
```

## Step 3: Configure Environment

```bash
# The .env file is in website/ - 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

# 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

All commands below should be run from the `website/` directory:

```bash
cd website

# Install PHP and Node dependencies
composer install
npm install
```

## Step 6: Run Migrations

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

# Run all migrations
php artisan migrate

# Set up Passport for OAuth2/SSO
php artisan passport:install

# Run seeders (roles, plans, admin user, optional demo data)
php artisan db:seed
```

## Step 7: Start Development Servers

All commands below should be run from the `website/` directory:

```bash
cd website

# One-shot: starts artisan serve + queue worker + pail log viewer + vite
composer run dev
```

## Step 8: 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 9: 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 main

# Navigate to Laravel directory
cd website

# Install any new dependencies
composer install
npm install

# Run migrations
php artisan migrate

# Start dev servers (all-in-one)
composer run dev
```

### Creating Features
```bash
# Commit directly to main (per project convention)
git add .
git commit -m "feat: add billing feature"

# Push to Gitea remote
git push origin main
```

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

# Run specific test
php artisan test --filter BillingServiceTest

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

## New Developer Checklist

Use this checklist when onboarding to the project:

- [x] Laravel 12 application cloned and `composer install` + `npm install` done
- [ ] `.env` configured (DB credentials, Stripe keys, PayPal credentials)
- [ ] Database created and connected
- [ ] `php artisan migrate` run successfully
- [ ] `php artisan passport:install` run
- [ ] `php artisan db:seed` run (roles, plans, admin user)
- [ ] `composer run dev` starts without errors
- [ ] Email sending working (test with Mailtrap initially)
- [ ] Stripe test keys configured
- [ ] PayPal sandbox credentials configured

## 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: Vite not compiling
**Solution**: Clear Vite cache: `npm run build`, then restart `composer run dev`

### Issue: Queue jobs not processing
**Solution**: Ensure `composer run dev` is running (it starts the queue worker automatically)

## 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
- [ ] ElastiFlow API access
- [ ] SMTP credentials (mail sending)
- [ ] Discord webhook URL
- [ ] Cloudflare API token (for DNS integration)

### Development Tools
- [ ] Gitea personal access token (for Gitea Actions/CI)
- [ ] 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
- **Cashier Documentation**: https://laravel.com/docs/12.x/billing
- **Vuetify Documentation**: https://vuetifyjs.com/en/
- **Project Planning Docs**: See CLAUDE.md, PROJECT_DEVELOPMENT.md, FEATURES.md
- **Issues**: https://git.ezscale.cloud/EZSCALE/website/issues

## Development Team

Add team member contact information here as project progresses.

---

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