Skip to content

DEVELOPMENT_SETUP.md

Latest commit

 

History

History
687 lines (504 loc) · 11.2 KB

DEVELOPMENT_SETUP.md

File metadata and controls

687 lines (504 loc) · 11.2 KB

Nimaora - Development Setup Guide

Complete Guide for Setting Up Your Development Environment

From zero to running in minutes

Table of Contents

Prerequisites

Required Software

Software Version Purpose
PHP 8.3+ Backend runtime
Composer 2.6+ PHP dependency manager
Node.js 22+ Frontend runtime
npm 10+ Node package manager
PostgreSQL 16+ Database
Redis 7+ Cache and queues
Docker 24+ Containerization
Git 2.40+ Version control

Installation Commands

macOS:

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install php@8.3 composer node postgresql@16 redis docker git

# Start services
brew services start postgresql@16
brew services start redis

Ubuntu/Debian:

# Add PHP repository
sudo add-apt-repository ppa:ondrej/php

# Update packages
sudo apt update

# Install dependencies
sudo apt install -y php8.3 php8.3-cli php8.3-fpm php8.3-pgsql php8.3-redis \
  php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-gd php8.3-bcmath \
  composer nodejs npm postgresql redis-server docker.io git

# Start services
sudo systemctl start postgresql redis-server docker
sudo systemctl enable postgresql redis-server docker

Windows (WSL2):

# Install WSL2
wsl --install

# In WSL2 Ubuntu, follow Ubuntu instructions above

Quick Start

Clone and Setup

# Clone repository
git clone https://git.dwin.codes/nimaora/nimaora.git
cd nimaora

# Run setup script
./scripts/setup-dev.sh

# Or manually:
# 1. Backend
cd nimaora-backend
composer install
cp .env.example .env
php artisan key:generate

# 2. Frontend
cd ../nimaora-frontend
npm install
cp .env.example .env.local

Start Development Servers

Terminal 1 - Backend API:

cd nimaora-backend
php artisan serve --host=0.0.0.0 --port=8000

Terminal 2 - WebSocket Server:

cd nimaora-backend
php artisan reverb:start --host=0.0.0.0 --port=8080

Terminal 3 - Queue Worker:

cd nimaora-backend
php artisan horizon

Terminal 4 - Frontend:

cd nimaora-frontend
npm run dev

Access Development Environment

Service URL
Frontend http://localhost:3000
Backend API http://localhost:8000/api
WebSocket ws://localhost:8080
Horizon Dashboard http://localhost:8000/horizon

Backend Setup

PHP Extensions

Ensure these extensions are enabled:

; php.ini
extension=pdo_pgsql
extension=redis
extension=mbstring
extension=xml
extension=curl
extension=zip
extension=gd
extension=bcmath
extension=sockets
extension=pcntl

Install Dependencies

cd nimaora-backend

# Install Composer dependencies
composer install

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

Environment Configuration

Edit .env file:

APP_NAME=Nimaora
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

# Database
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=nimaora
DB_USERNAME=postgres
DB_PASSWORD=secret

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null

# Queue
QUEUE_CONNECTION=redis

# Broadcasting
BROADCAST_CONNECTION=reverb
REVERB_APP_ID=nimaora
REVERB_APP_KEY=nimaora-dev-key
REVERB_APP_SECRET=nimaora-dev-secret
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=http

# Frontend URL (for CORS)
FRONTEND_URL=http://localhost:3000

Database Setup

# Create database
createdb nimaora

# Run migrations
php artisan migrate

# Seed test data
php artisan db:seed

# Or both at once
php artisan migrate:fresh --seed

Laravel Octane (Optional - High Performance)

# Install Swoole
pecl install swoole

# Start with Octane
php artisan octane:start --host=0.0.0.0 --port=8000

# Or use watch for auto-reload
php artisan octane:start --watch

Frontend Setup

Install Dependencies

cd nimaora-frontend

# Install npm packages
npm install

# Copy environment file
cp .env.example .env.local

Environment Configuration

Edit .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000/api
NEXT_PUBLIC_REVERB_APP_KEY=nimaora-dev-key
NEXT_PUBLIC_REVERB_HOST=localhost
NEXT_PUBLIC_REVERB_PORT=8080
NEXT_PUBLIC_REVERB_SCHEME=http

Development Server

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linting
npm run lint

# Type checking
npm run type-check

Database Setup

Create Database User

# Connect to PostgreSQL
psql -U postgres

# Create user
CREATE USER nimaora WITH PASSWORD 'secret';

# Create database
CREATE DATABASE nimaora OWNER nimaora;

# Grant privileges
GRANT ALL PRIVILEGES ON DATABASE nimaora TO nimaora;

# Exit
\q

Migrations

cd nimaora-backend

# Run all migrations
php artisan migrate

# Rollback last migration
php artisan migrate:rollback

# Rollback all and re-migrate
php artisan migrate:fresh

# With seeding
php artisan migrate:fresh --seed

Seeders

# Run all seeders
php artisan db:seed

# Run specific seeder
php artisan db:seed --class=BattleSeeder

# Create new seeder
php artisan make:seeder QuestionSeeder

WebSocket Setup

Laravel Reverb

cd nimaora-backend

# Start Reverb server
php artisan reverb:start --host=0.0.0.0 --port=8080

# With debug output
php artisan reverb:start --host=0.0.0.0 --port=8080 --debug

Testing WebSocket

# Install wscat
npm install -g wscat

# Connect to WebSocket
wscat -c ws://localhost:8080/app/nimaora-dev-key

# Send subscription
{"event":"pusher:subscribe","data":{"channel":"battle.1"}}

Docker Development

Using Docker Compose

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

# Rebuild containers
docker compose build --no-cache

Development with Docker

# Start only infrastructure (DB, Redis, RabbitMQ)
docker compose up -d postgres-primary redis-master rabbitmq

# Run backend locally
cd nimaora-backend
php artisan serve

# Run frontend locally
cd nimaora-frontend
npm run dev

Useful Docker Commands

# Execute command in container
docker compose exec backend php artisan migrate

# Access container shell
docker compose exec backend sh

# View container logs
docker compose logs -f backend

# Restart specific service
docker compose restart backend

IDE Configuration

VS Code

Recommended Extensions:

  • PHP Intelephense
  • Laravel Extra Intellisense
  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • GitLens

settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[php]": {
    "editor.defaultFormatter": "bmewburn.vscode-intelephense-client"
  },
  "php.validate.executablePath": "/usr/bin/php",
  "intelephense.environment.phpVersion": "8.3.0",
  "typescript.preferences.importModuleSpecifier": "relative"
}

PhpStorm

Recommended Plugins:

  • Laravel Plugin
  • Laravel Idea
  • .env files support

Settings:

  1. Enable Laravel Plugin
  2. Set PHP interpreter to 8.3
  3. Configure Composer
  4. Set up database connection
  5. Enable TypeScript support

Development Workflow

Git Workflow

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push branch
git push origin feature/my-feature

# Create pull request via GitHub/GitLab

Commit Convention

Follow Conventional Commits:

feat: add new feature
fix: fix bug
docs: update documentation
style: formatting changes
refactor: code refactoring
test: add tests
chore: maintenance tasks

Code Quality

# Backend
cd nimaora-backend
./vendor/bin/pint          # Laravel Pint (code style)
./vendor/bin/phpstan       # Static analysis
php artisan test           # Run tests

# Frontend
cd nimaora-frontend
npm run lint               # ESLint
npm run type-check         # TypeScript check
npm run test               # Run tests

Debugging

Backend Debugging

Laravel Telescope:

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate
# Access: http://localhost:8000/telescope

Xdebug Configuration:

; php.ini
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

Debug Logging:

// Quick debug
dd($variable);
dump($variable);

// Log to file
Log::debug('Message', ['data' => $data]);

// Laravel Ray (if installed)
ray($variable);

Frontend Debugging

React DevTools:

  • Install Chrome/Firefox extension
  • Inspect component tree and state

Console Logging:

console.log('Debug:', data);
console.table(arrayData);
console.group('Group');
console.log('Item 1');
console.groupEnd();

Network Debugging:

  • Use browser Network tab
  • Check WebSocket frames

Common Issues

Backend Issues

1. Composer Install Fails

# Update Composer
composer self-update

# Clear cache
composer clear-cache

# Install with verbose
composer install -vvv

2. Database Connection Error

# Check PostgreSQL is running
pg_isready

# Check credentials in .env
php artisan config:clear

3. Redis Connection Error

# Check Redis is running
redis-cli ping

# Check Redis config
php artisan config:cache

4. Permission Issues

# Fix storage permissions
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Frontend Issues

1. Node Modules Error

# Clear and reinstall
rm -rf node_modules package-lock.json
npm install

2. TypeScript Errors

# Regenerate types
npm run type-check

3. Environment Variables Not Loading

# Prefix with NEXT_PUBLIC_ for client-side
# Restart dev server after changes
npm run dev

WebSocket Issues

1. Connection Refused

# Check Reverb is running
ps aux | grep reverb

# Restart Reverb
php artisan reverb:start

2. Authentication Errors

# Clear config cache
php artisan config:clear
php artisan cache:clear

Development Resources

Documentation

Tools

Happy Coding!