EZSCALE/website
SHA256
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove ipv4-outreach-tickets.txt; refresh GETTING_STARTED

Browse Source 
Outreach notes don't belong in the repo. GETTING_STARTED reconciled
against current composer/npm scripts: fix Gitea clone URL, drop Vuexy
references, remove Redis requirement, replace multi-terminal startup
with `composer run dev`, update PHP/Node versions to 8.3/24, fix
branch workflow to main. TASKS.md: mark multi-currency and KB as done,
fix CI/CD reference from GitHub to Gitea Actions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Murray
2026-04-26 22:40:18 -04:00
parent ab3a195e85
commit efe3fa53a4
3 changed files with 45 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
GETTING_STARTED.md
View File

@@ -5,38 +5,33 @@ This guide will help you start building the EZSCALE Billing Platform on your dev
## Prerequisites
### Required Software
- **PHP** 8.2 or higher
- **PHP** 8.3 or higher
- **Composer** 2.x
- **Node.js** 18.x or higher
- **npm** 9.x or higher
- **Node.js** 24.x or higher
- **npm** 10.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
git clone git@git.ezscale.cloud:EZSCALE/website.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).
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
# Create develop branch
git checkout -b develop
```
## Step 3: Configure Environment
@@ -56,11 +51,6 @@ 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_...
@@ -101,110 +91,39 @@ All commands below should be run from the `website/` directory:
```bash
cd website
# Install base PHP dependencies (already in composer.json from base install)
# Install PHP and Node dependencies
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
```bash
# 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
## Step 6: 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
# Set up Passport for OAuth2/SSO
php artisan passport:install
```bash
# Create seeders
php artisan make:seeder RoleSeeder
php artisan make:seeder PlanSeeder
php artisan make:seeder DatacenterSeeder
# Run seeders
# Run seeders (roles, plans, admin user, optional demo data)
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
## Step 7: Start Development Servers
All commands below should be run from the `website/` directory:
```bash
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
# One-shot: starts artisan serve + queue worker + pail log viewer + vite
composer run dev
```
## Step 11: Configure Local Domains (Optional)
## Step 8: Configure Local Domains (Optional)
If using Laravel Herd or Valet, you can set up local domains:
@@ -220,7 +139,7 @@ Update `.env`:
APP_URL=http://ezscale.test
```
## Step 12: Set Up Testing
## Step 9: Set Up Testing
```bash
# Create test database
@@ -238,7 +157,7 @@ php artisan test
### Daily Development
```bash
# Pull latest changes
git pull origin develop
git pull origin main
# Navigate to Laravel directory
cd website
@@ -250,27 +169,18 @@ npm install
# Run migrations
php artisan migrate
# Start dev servers
php artisan serve
npm run dev
php artisan queue:work
# Start dev servers (all-in-one)
composer run dev
```
### Creating Features
```bash
# Create feature branch from develop
git checkout develop
git pull
git checkout -b feature/billing-system
# Make changes, commit often
# Commit directly to main (per project convention)
git add .
git commit -m "Add Stripe billing service"
git commit -m "feat: add billing feature"
# Push to remote
git push origin feature/billing-system
# Create PR on GitHub: feature/billing-system -> develop
# Push to Gitea remote
git push origin main
```
### Running Tests
@@ -285,37 +195,20 @@ php artisan test --filter BillingServiceTest
php artisan test --coverage
```
## Phase 1 Checklist
## New Developer Checklist
Use this checklist to track Phase 1 Foundation progress:
Use this checklist when onboarding to the project:
- [x] Laravel 12 project initialized (base install in `website/`)
- [ ] Vuexy theme integrated
- [ ] Environment configured (.env)
- [x] Laravel 12 application cloned and `composer install` + `npm install` done
- [ ] `.env` configured (DB credentials, Stripe keys, PayPal credentials)
- [ ] 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
- [ ] `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)
- [ ] Git repository initialized
- [ ] CI/CD pipeline set up (GitHub Actions)
- [ ] Staging environment created
- [ ] Stripe test keys configured
- [ ] PayPal sandbox credentials configured
## Common Issues & Solutions
@@ -328,14 +221,11 @@ Use this checklist to track Phase 1 Foundation progress:
### 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`
**Solution**: Clear Vite cache: `npm run build`, then restart `composer run dev`
### Issue: Queue jobs not processing
**Solution**: Ensure `php artisan queue:work` is running, check Redis connection
**Solution**: Ensure `composer run dev` is running (it starts the queue worker automatically)
## API Credentials You'll Need
@@ -354,16 +244,13 @@ Before full development, obtain these API credentials:
- [ ] Enhance API key
### External Services
- [ ] SupportPal API credentials
- [ ] ElastiFlow API access
- [ ] Mailgun or SendGrid API key
- [ ] SMTP credentials (mail sending)
- [ ] 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)
- [ ] Gitea personal access token (for Gitea Actions/CI)
- [ ] Sentry DSN (for error tracking - optional)
## Documentation Reference
@@ -388,9 +275,10 @@ Once Phase 1 is complete:
## 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
- **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