# 🐳 BuyerKiosk Docker Development Environment

This Docker setup provides a complete local development environment for BuyerKiosk.

## Quick Start

```bash
# Start everything
./docker-dev.sh up

# Open in browser
open http://localhost:8080
```

## Services

| Service | URL/Port | Purpose |
|---------|----------|---------|
| **Web App** | http://localhost:8080 | Main application |
| **Adminer** | http://localhost:8081 | Database management |
| **Mailhog** | http://localhost:8025 | Email testing |
| **MySQL** | localhost:3307 | Database (user: `kiosk_db`, pass: `kiosk_dev_password`) |
| **Redis** | localhost:6380 | Cache & queues |

## Common Commands

```bash
# Start/stop
./docker-dev.sh up          # Start all containers
./docker-dev.sh down        # Stop all containers
./docker-dev.sh restart     # Restart containers

# Development
./docker-dev.sh shell       # Open bash in web container
./docker-dev.sh logs        # Tail web container logs
./docker-dev.sh logs mysql  # Tail mysql logs

# Testing
./docker-dev.sh test        # Run all tests
./docker-dev.sh test --unit # Run unit tests only

# Database
./docker-dev.sh mysql       # Open MySQL CLI
./docker-dev.sh migrate     # Run migrations

# CSS
./docker-dev.sh css         # Build CSS (minified)
./docker-dev.sh css-watch   # Watch for CSS changes

# Background jobs
./docker-dev.sh worker      # Start TaskEngine worker
./docker-dev.sh queue-status # Check queue depths

# Composer
./docker-dev.sh composer install
./docker-dev.sh composer require package/name

# Maintenance
./docker-dev.sh status      # Show container status
./docker-dev.sh clean       # Remove volumes (⚠️ deletes data)
./docker-dev.sh reset       # Full rebuild (⚠️ deletes everything)
```

## First Time Setup

1. **Copy environment template** (or let Docker handle it):
   ```bash
   cp userfrosting/.env.docker userfrosting/.env
   ```

2. **Start the containers**:
   ```bash
   ./docker-dev.sh up
   ```

3. **Run migrations** (first time only):
   ```bash
   ./docker-dev.sh migrate
   ```

4. **Import existing data** (optional):
   ```bash
   # Connect to MySQL and import your dump
   ./docker-dev.sh mysql < your_dump.sql
   ```

## Configuration

### Environment Variables

Edit `userfrosting/.env` or `userfrosting/.env.docker` for:
- External service API keys (Twilio, Ably, etc.)
- Application settings
- Feature flags

### Custom Docker Compose

Create `docker-compose.override.yml` to customize without modifying the main file:

```yaml
# docker-compose.override.yml
services:
  web:
    environment:
      - XDEBUG_MODE=debug
      - SOME_OTHER_VAR=value
```

## Xdebug (PHP Debugging)

Xdebug is pre-configured but disabled by default. To enable:

1. Create `docker-compose.override.yml`:
   ```yaml
   services:
     web:
       build:
         context: .
         args:
           - INSTALL_XDEBUG=true
   ```

2. Rebuild: `./docker-dev.sh build && ./docker-dev.sh up`

3. Configure your IDE to listen on port 9003

## Database Access

### Via Adminer (Web UI)
- URL: http://localhost:8081
- Server: `mysql`
- Username: `kiosk_db`
- Password: `kiosk_dev_password`

### Via MySQL CLI
```bash
./docker-dev.sh mysql
```

### Via External Client (TablePlus, DBeaver, etc.)
- Host: `localhost`
- Port: `3307`
- User: `kiosk_db`
- Password: `kiosk_dev_password`

## Troubleshooting

### Container won't start
```bash
# Check logs
./docker-dev.sh logs

# Rebuild
./docker-dev.sh build
./docker-dev.sh up
```

### Permission issues
```bash
# Fix permissions inside container
./docker-dev.sh shell
chown -R www-data:www-data /var/www/html/logs
```

### MySQL connection refused
Wait a few seconds - MySQL takes time to initialize on first run. Check status with:
```bash
docker-compose ps
docker-compose logs mysql
```

### Need a fresh start?
```bash
./docker-dev.sh reset  # ⚠️ Destroys all data!
```

## Directory Structure

```
docker/
├── README.md           # This file
├── entrypoint.sh       # Container startup script
├── php/
│   └── custom.ini      # PHP configuration
└── mysql/
    ├── init/
    │   └── 01-create-databases.sql  # Initial DB setup
    └── conf.d/
        └── my.cnf      # MySQL configuration
```

## Notes

- **Ports**: Web uses 8080 (not 80) to avoid conflicts
- **MySQL**: Port 3307 (not 3306) to avoid conflicts with local MySQL
- **Volumes**: Data persists in Docker volumes between restarts
- **Logs**: Shared with host at `./logs/`