EZSCALE/website

SHA256

Fork 0

Files

Claude Dev cf7669f270 Updated

2026-02-09 01:49:02 -05:00

9.3 KiB

Raw Blame History

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

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

The Laravel 12 application is already installed in the website/ directory as a base install (no additional packages or customizations yet).

Step 2: Navigate to Laravel Directory

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

# Create develop branch
git checkout -b develop

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

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

# 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 base PHP dependencies (already in composer.json from base install)
composer install

# Install additional PHP dependencies for the project
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

# Extract Vuexy theme source files to:
# website/resources/js/vuexy/
# website/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

# 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

# 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

# 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

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

cd website

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

# 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

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

# Navigate to Laravel directory
cd website

# 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

# 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

# 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 (base install in website/)
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:

Review Phase 1 deliverables
Demo authentication flow
Verify all integrations are working (test API connections)
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!

9.3 KiB Raw Blame History