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

# 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

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

Step 3: Configure Environment

# 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

# 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:

cd website

# Install PHP and Node dependencies
composer install
npm install

Step 6: Run Migrations

# 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:

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:

# 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

# 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

# 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

# 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

# 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:

• 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!