# Detailed Setup Guide - Web Dolphin Japan

This guide provides step-by-step instructions to set up the Web Dolphin Japan project on your local machine.

> **Backend API-Only Project:** This is a REST API server with no frontend code. All setup focuses on the PHP/Laravel backend.

## Prerequisites

Before you begin, ensure you have the following installed:

### 1. PHP 8.2 or Higher
```bash
# Check your PHP version
php --version

# Should output: PHP 8.2.x or higher
```
[Download PHP](https://www.php.net/downloads) if not installed.

### 2. Composer (PHP Dependency Manager)
```bash
# Check if Composer is installed
composer --version

# Should output: Composer version 2.x.x
```
[Install Composer](https://getcomposer.org/download/) if needed.

### 3. PostgreSQL
```bash
# Check if PostgreSQL is installed
psql --version

# Should output: psql (PostgreSQL) x.x.x
```
[Download PostgreSQL](https://www.postgresql.org/download/) if not installed.

### 4. Git
```bash
# Check if Git is installed
git --version

# Should output: git version 2.x.x
```
[Install Git](https://git-scm.com/) if needed.

---

## Step-by-Step Setup Instructions

### Step 1: Clone the Repository

```bash
# Clone the repository to your machine
git clone https://github.com/yourusername/web-dolphin-japan.git

# Navigate into the project directory
cd web-dolphin-japan
```

### Step 2: Install PHP Dependencies

```bash
# Install all Composer dependencies
composer install

# This will create a vendor/ folder with all PHP packages
```

**If you encounter issues:**
- Clear Composer cache: `composer clear-cache`
- Delete `composer.lock`: `rm composer.lock`
- Try again: `composer install`

### Step 3: Create Environment Configuration

```bash
# Copy the example environment file
cp .env.example .env
```

Open `.env` and configure as needed:

```env
# Application Settings
APP_NAME=Web-Dolphin-Japan
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

# Database Configuration (PostgreSQL)
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=dolphinapp
DB_USERNAME=postgres
DB_PASSWORD=your_password
```

### Step 4: Generate Application Key

```bash
# Generate a unique encryption key for your application
php artisan key:generate

# You should see: Application key set successfully.
```

### Step 5: Setup PostgreSQL Database

```bash
# 1. Start PostgreSQL service
# Linux:
sudo systemctl start postgresql

# macOS:
brew services start postgresql

# Windows: Start PostgreSQL from Services

# 2. Create the database
creatdb -U postgres dolphinapp

# OR if you need to set a password:
psql -U postgres -c "CREATE DATABASE dolphinapp;"

# 3. Verify connection in .env (should already be configured)
# DB_HOST=127.0.0.1
# DB_PORT=5432
# DB_DATABASE=dolphinapp
# DB_USERNAME=postgres
# DB_PASSWORD=your_password

# 4. Run migrations to create tables
php artisan migrate

# You should see: Migration table created successfully
#                Migrating: 0001_01_01_000000_create_users_table
#                Migrated: 0001_01_01_000000_create_users_table (etc.)

# 5. (Optional) Seed the database
php artisan db:seed
```

### Step 6: Set Proper File Permissions (Linux/Mac Only)

```bash
# Make storage and bootstrap directories writable
chmod -R 775 storage bootstrap/cache

# If you encounter permission issues:
chmod -R 777 storage bootstrap/cache
```

### Step 7: Verify Installation

```bash
# Test the application by running the dev server
php artisan serve

# You should see:
# Laravel development server started: http://127.0.0.1:8000

# Open in your browser: http://localhost:8000
```

---

## Alternative: Quick Setup with Single Command

If you completed all prerequisites, you can run everything at once:

```bash
composer run setup
```

This executes all the above steps automatically:
- ✅ Installs Composer dependencies
- ✅ Creates .env file
- ✅ Generates app key
- ✅ Runs migrations

---

## Starting Development

### Option 1: Single Command (Recommended)

```bash
# Starts everything: Laravel, queue, and logs watcher
composer run dev
```

This command runs:
- **Laravel Server**: http://localhost:8000
- **Queue Listener**: Processes background jobs
- **Pail Logger**: Streams application logs in real-time

### Option 2: Individual Services

Run each in a separate terminal:

```bash
# Terminal 1: Laravel development server
php artisan serve

# Terminal 2: Queue job processing
php artisan queue:listen --tries=1 --timeout=0

# Terminal 3: Stream logs
php artisan pail
```

---

## Database Troubleshooting

### "SQLSTATE[08006]: Connection failure"

**Solution:**
```bash
# Ensure PostgreSQL is running
# Linux:
sudo systemctl status postgresql

# macOS:
brew services list | grep postgresql

# Windows: Check PostgreSQL is running in Services

# Verify connection settings in .env:
# DB_HOST=127.0.0.1
# DB_PORT=5432
# DB_DATABASE=dolphinapp
# DB_USERNAME=postgres
```

### "SQLSTATE[08006] [7] FATAL: database does not exist"

**Solution:**
```bash
# Create the database
creatdb -U postgres dolphinapp

# Then run migrations
php artisan migrate
```

### "SQLSTATE[08P01] [3] FATAL: password authentication failed"

**Solution:**
- Verify DB_USERNAME and DB_PASSWORD in .env match PostgreSQL user
- Reset PostgreSQL password:
  ```bash
  sudo -u postgres psql
  ALTER USER postgres WITH PASSWORD 'new_password';
  \q
  ```

---

## Testing the API

### Using cURL

```bash
# Start the server first
php artisan serve

# In another terminal, test a brand endpoint
curl http://localhost:8000/api/v1/brand/
```

### Using Postman

1. Import base URL: `http://localhost:8000`
2. Test endpoint: `GET /api/v1/brand/`
3. Expected response:
```json
{
  "code": 200,
  "hasError": false,
  "result": {
    "data": [],
    "current_page": 1
  }
}
```

### Using Laravel Tinker (Interactive REPL)

```bash
# Start tinker
php artisan tinker

# Now you can run PHP commands
>>> App\Models\Brand::all()
>>> App\Models\Brand::create(['name' => 'Toyota'])
>>> exit
```

---

## Running Tests

```bash
# Run all tests
composer run test

# Run a specific test file
php artisan test tests/Feature/ExampleTest.php

# Run tests with coverage
php artisan test --coverage
```

---

## Code Quality

```bash
# Check code style (PSR-12)
./vendor/bin/pint --test

# Auto-fix code style
./vendor/bin/pint
```

---

## Common Issues & Solutions

| Issue | Solution |
|-------|----------|
| `Composer: command not found` | Install Composer globally or use `php composer.phar` |
| `php: command not found` | Install PHP or add to PATH |
| `SQLSTATE[08006]` | Ensure PostgreSQL is running and database exists |
| `No composer.json found` | Ensure you're in the project root directory |
| `Port 8000 already in use` | Run on different port: `php artisan serve --port=8001` |
| `Permission denied on storage/` | Run: `chmod -R 775 storage bootstrap/cache` |

---

## After Setup

### Recommended Next Steps

1. **Read the Architecture Guide**: [AGENTS.md](AGENTS.md)
2. **Explore the Brand Example**: `app/Http/Controllers/Admin/BrandController.php`
3. **Review Database Migrations**: `database/migrations/`
4. **Check Routes**: `routes/web.php`
5. **Start Building**: Follow the 3-layer architecture pattern

### Project Commands Reference

```bash
# Core
php artisan serve              # Start dev server
composer run dev               # Start all services
composer run test              # Run tests

# Database
php artisan migrate            # Run pending migrations
php artisan migrate:fresh      # Reset and run migrations
php artisan db:seed            # Seed the database
php artisan tinker             # Interactive shell

# Code Quality
./vendor/bin/pint              # Fix code style
./vendor/bin/pint --test       # Check code style

# Useful
php artisan route:list         # Show all routes
php artisan config:show        # Show configuration
php artisan env                # Show environment (local/production)
```

---

## Getting Help

- **Laravel Documentation**: https://laravel.com/docs/12
- **Eloquent ORM**: https://laravel.com/docs/12/eloquent
- **Vite Guide**: https://vitejs.dev/
- **Team Members**: Reach out to your team for questions

---

**Need Help?** Check [README.md](README.md) or reach out to the development team.

Last Updated: May 5, 2026