Init Commit
This commit is contained in:
Claude EZSCALE
393
GETTING_STARTED.md
Normal file
393
GETTING_STARTED.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user