# Local Setup

Getting a working development environment. For deploying, see
[DEPLOY.md](DEPLOY.md).

## Prerequisites

PHP, Composer and Node. The required PHP version is declared in
`composer.json` (`require.php` and `config.platform.php`) — it is pinned to
match production, so read it there rather than trusting a version written
here.

## Steps

### 1. Environment Configuration

Create a copy of the `.env.example` file:

```bash
cp .env.example .env
```

`.env.example` marks which values you must supply (database, mail and
Stripe credentials); everything else already has a working default. The
list is not repeated here so it cannot fall out of step with the file.

### 2. Install Dependencies

```bash
# Install PHP dependencies
composer update

# Install Node.js dependencies
npm install
```

### 3. Setup Laravel

```bash
# Create storage link
php artisan storage:link
```

### 4. Database Setup

Choose one of the following options:

#### Option A: Clean Database (Fresh Start)
```bash
# Create empty SQLite database
touch database/database.sqlite

# Set proper permissions for database file and directory
chmod 666 database/database.sqlite && chmod 777 database/

# Run migrations to create tables
php artisan migrate
```

#### Option B: Use MySQL Dump (Import Production Data)
**Note:** Place your MySQL dump file named `dump.sql` in the `database/` directory before proceeding.

```bash
# Navigate to database directory
cd database

# Step 1: Make the mysql2sqlite script executable
chmod +x mysql2sqlite

# Step 2: Convert MySQL dump file to SQLite-compatible format (~3-5 minutes)
# This reads the MySQL dump file and converts SQL syntax to SQLite format
./mysql2sqlite dump.sql > dump_sqlite.sql

# Step 3: Import the converted SQL into the SQLite database (~1 minute)
# This creates/updates the database.sqlite file with the converted data
sqlite3 database.sqlite < dump_sqlite.sql

# Step 4: Set proper permissions for database file and directory
chmod 666 database.sqlite && chmod 777 ../database/

# Step 5: Create sensitive tables (not included in dump)
php artisan setup:local

# Step 6: Return to project root
cd ..
```

**Prerequisites for Option B:**
- Ensure you have `sqlite3` installed on your system
- Have a MySQL dump file named `dump.sql` in the `database/` directory
- The `mysql2sqlite` script should be present in the `database/` directory

**Notes:**
- The `mysql2sqlite` script handles common MySQL-to-SQLite syntax conversions
- Always backup your existing database before running the migration
- Review the generated `dump_sqlite.sql` file before importing if you encounter issues

#### Option C: Remote SSH Connection (Access Development Database)
```bash
ssh -i {username}.pem -N -L 8889:127.0.0.1:3306 -L 6380:127.0.0.1:6379 tunnel-user@diecastdetective.com
# Example: ssh -i josh.pem -N -L 8889:127.0.0.1:3306 -L 6380:127.0.0.1:6379 tunnel-user@diecastdetective.com
```

**Note:** This connects to dev.diecastdetective.com.au, not the production site.

**For Options A & B (SQLite), ensure your `.env` file has:**
```
DB_CONNECTION=sqlite
DB_DATABASE=database/database.sqlite # Use an absolute path for SQLite if not found
CACHE_DRIVER=database
CACHE_STORE=database
```

**For Option C (Remote SSH), ensure your `.env` file has:**
```
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=8889
DB_DATABASE=dev
CACHE_DRIVER=redis
CACHE_STORE=redis
```

### 5. Start Development Servers

Open two terminal windows and run:

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

# Terminal 2: Start Vite development server
npm run dev
```

### 6. Access the Application

- Main application: http://localhost:8000
- Vite development server: http://localhost:5173

### 7. Initialize Autocomplete Data (Optional)

To enable search autocomplete functionality, run the following command to regenerate product data:

```bash
php artisan prods:regenerate
```

**Note:** This command generates the `prods.json` file that powers the search autocomplete functionality. It processes all products in the database and creates a JSON file containing product information (codes, brands, models, drivers, etc.) for fast client-side searching. Run this after setting up your database to ensure search functionality works properly.

## Database inspection

A web UI for browsing the local SQLite database — browse tables, edit rows,
run queries.

**Access:** http://localhost:8000/db-admin (password: `diecastdetective`)

**Note:** This tool is automatically excluded from production builds.