Installation & Local Setup Guide#

Target: Local development environment for Loreax on macOS/Linux
Time: ~30 minutes
Difficulty: Intermediate

📋 Prerequisites#

Before starting, ensure you have:

System Requirements#

• macOS 11+ or Ubuntu 20.04+ (or WSL2 on Windows)
• 8GB+ RAM (16GB recommended for comfortable development)
• 10GB+ free disk space
• Internet connection (for package downloads)

Required Software#

Required System Extensions (PHP)#

# Verify extensions are installed
php -m | grep -E "(pdo|pgsql|redis|mongodb|gd|bcmath|intl)"

# Verify MongoDB extension version (must be 2.2+)
php -r "echo 'ext-mongodb: ' . phpversion('mongodb') . PHP_EOL;"

Should show:

• pdo_pgsql — PostgreSQL database driver
• redis — Redis client
• mongodb — MongoDB client (version 2.2.0 or higher required)
• gd — Image manipulation
• bcmath — Arbitrary precision arithmetic
• intl — Internationalization

Important: The MongoDB PHP extension must be version 2.2+ for compatibility with mongodb/mongodb package 2.2.x. If you have an older version, upgrade via PECL: pecl install --force mongodb

🚀 Installation Steps#

Step 1: Install System Dependencies#

macOS (Homebrew)#

# Install prerequisites
brew install php@8.4 composer node@20 docker git

# Verify versions
php --version       # Should be 8.4+
composer --version  # Should be 2.x+
node --version      # Should be 20.x+

Ubuntu/Debian#

# Update package list
sudo apt-get update

# Install PHP 8.4 and extensions
sudo apt-get install -y \
  php8.4-cli \
  php8.4-fpm \
  php8.4-pdo \
  php8.4-pgsql \
  php8.4-redis \
  php8.4-gd \
  php8.4-bcmath \
  php8.4-intl \
  php8.4-xml \
  php8.4-dev \
  pkg-config \
  libssl-dev

# Install MongoDB extension via PECL (to get 2.2+)
sudo pecl install mongodb
echo "extension=mongodb.so" | sudo tee /etc/php/8.4/cli/conf.d/20-mongodb.ini
echo "extension=mongodb.so" | sudo tee /etc/php/8.4/fpm/conf.d/20-mongodb.ini

# Verify MongoDB extension version
php -r "echo 'ext-mongodb: ' . phpversion('mongodb') . PHP_EOL;"

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Install Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Step 2: Clone Repository#

# Clone the repository
git clone git@github.com:bervant/loreax-core.git
cd loreax-core

# Verify you're on the correct branch
git branch --show-current

Step 3: Start Docker Services#

# Start PostgreSQL, Redis, MongoDB containers
docker-compose up -d

# Verify containers are running
docker-compose ps
# Should show:
#   loreax-postgres  - PostgreSQL 16
#   loreax-redis     - Redis 7
#   loreax-mongodb   - MongoDB 7

# Wait for MongoDB to be ready (check logs)
docker-compose logs mongodb | grep "waiting for connections"

Step 4: Install PHP Dependencies#

# Install Composer dependencies
composer install

# Verify installation
composer --version
./vendor/bin/phpunit --version

Step 5: Install Node Dependencies#

# Install npm packages
npm install

# Verify installation
npm --version
npm list | head -5

Step 6: Configure Environment#

# Copy environment template
cp .env.example .env

# Generate application key
php artisan key:generate

# Verify .env was created
cat .env | head -10

Step 7: Configure Database Connection#

Edit .env and ensure these values match your Docker setup:

# Database (PostgreSQL)
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=loreax
DB_USERNAME=loreax
DB_PASSWORD=secret

# Cache (Redis)
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0

# Request Logs (MongoDB)
MONGODB_DSN=mongodb://loreax:secret@127.0.0.1:27017/loreax_logs
MONGODB_DATABASE=loreax_logs

# Media (S3 - local mock)
AWS_ACCESS_KEY_ID=testing
AWS_SECRET_ACCESS_KEY=testing
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=loreax-local
AWS_ENDPOINT=http://127.0.0.1:9000  # MinIO local S3 mock (optional)

Step 8: Run Database Migrations#

# Run all pending migrations
php artisan migrate:fresh

# Verify migrations completed
php artisan migrate:status

# (Optional) Seed sample data
php artisan db:seed

Step 9: Generate OpenAPI Documentation#

# Generate Swagger/OpenAPI docs
php artisan l5-swagger:generate

# Check generation was successful
ls -lh storage/api-docs/

Step 10: Start Development Server#

# Terminal 1: Start Laravel development server
php artisan serve

# Output: Laravel development server started at [http://127.0.0.1:8000]

# Terminal 2: Start job queue worker (in new terminal)
php artisan horizon

# Output: Horizon started successfully

# Terminal 3: Compile assets (in new terminal, watch for changes)
npm run dev

# Output: ✓ built in XXXms

✅ Verification Checklist#

Health Checks#

# 1. API is responding
curl http://localhost:8000/health
# Expected: {"status": "ok"}

# 2. Database is connected
curl http://localhost:8000/ready
# Expected: {"ready": true}

# 3. All tests pass
./vendor/bin/phpunit
# Expected: OK (533 tests, 1960 assertions)

# 4. Code style complies
./vendor/bin/pint --test
# Expected: PASS (all files)

# 5. Static analysis passes
./vendor/bin/phpstan analyse
# Expected: [OK] No errors

Access Points#

Open these in your browser to verify everything works:

Test Accounts#

After seeding, these accounts are available:

Admin User:
  Email: admin@loreax.test
  Password: password
  Realm: admin

Creator User:
  Email: creator@loreax.test
  Password: password
  Realm: user

Fan User:
  Email: fan@loreax.test
  Password: password
  Realm: user

🔧 Troubleshooting#

Docker Services Won't Start#

# Check Docker daemon is running
docker ps

# Check compose file is valid
docker-compose config

# View service logs
docker-compose logs postgresql
docker-compose logs redis
docker-compose logs mongodb

# Restart all services
docker-compose restart

PHP Extension Missing#

# Check which extensions are missing
php -m | grep -v pdo_pgsql
php -m | grep -v redis
php -m | grep -v mongodb

# On macOS (Homebrew), reinstall PHP with extensions
brew reinstall php@8.4

# On Ubuntu, install missing extension
sudo apt-get install php8.4-<extension-name>

Composer Install Fails#

# Clear composer cache
composer clear-cache

# Update composer itself
composer self-update

# Try install again
composer install -vv  # Verbose output for debugging

Database Migrations Fail#

# Check database connection
php artisan tinker
> DB::connection()->getPdo();  # Should not throw error

# View migration status
php artisan migrate:status

# Reset and start fresh
php artisan migrate:fresh --seed

Port Already in Use#

# If port 8000 is in use, specify different port
php artisan serve --port=8080

# If port 5432 (PostgreSQL) is in use, check what's running
lsof -i :5432

# If port 6379 (Redis) is in use
lsof -i :6379

# Change Docker port mappings in docker-compose.yml
# Then restart: docker-compose down && docker-compose up -d

npm run dev Fails#

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Try build again
npm run dev

📚 Next Steps#

1. Read Configuration Guide: 02-CONFIGURATION.md
2. Understand File Structure: 03-FILE-STRUCTURE.md
3. Learn Domain Architecture: 04-DOMAINS/INDEX.md
4. Start Developer Onboarding: 05-ONBOARDING.md

📞 Support#

• Issues with setup: Check Troubleshooting section
• Docker issues: docker-compose logs <service>
• PHP issues: php -v && php -m
• Slack: #loreax-dev

Last Updated: April 25, 2026