# Local Testing Guide - Windows/Mac/Linux

This guide helps you test the Teren App Docker setup on your local machine without WireGuard VPN.

## Quick Start

### 1. Prerequisites

- Docker Desktop installed and running
- Git
- 8GB RAM recommended  
- Ports available: 8080, 5433 (PostgreSQL), 5050, 6379, 9000, 8025, 1025
- **Note:** If you have local PostgreSQL on port 5432, the Docker container uses 5433 instead

### 2. Setup

```bash
# Clone repository (if not already)
git clone YOUR_GITEA_URL
cd Teren-app

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

# Start all services
docker compose -f docker-compose.local.yaml up -d

# Wait for services to start (30 seconds)
timeout 30

# Generate application key
docker compose -f docker-compose.local.yaml exec app php artisan key:generate

# Run migrations
docker compose -f docker-compose.local.yaml exec app php artisan migrate

# Seed database (optional)
docker compose -f docker-compose.local.yaml exec app php artisan db:seed

# Install frontend dependencies (if needed)
npm install
npm run dev
```

### 3. Access Services

| Service | URL | Credentials |
|---------|-----|-------------|
| **Laravel App** | http://localhost:8080 | - |
| **Portainer** | http://localhost:9000 | Set on first visit |
| **pgAdmin** | http://localhost:5050 | admin@local.dev / admin |
| **Mailpit** | http://localhost:8025 | - |
| **PostgreSQL** | localhost:5433 | teren_user / local_password |
| **Redis** | localhost:6379 | - |

**Note:** PostgreSQL uses port 5433 to avoid conflicts with any local PostgreSQL installation.

## Common Commands

### Docker Compose Commands

```bash
# Start all services
docker compose -f docker-compose.local.yaml up -d

# Stop all services
docker compose -f docker-compose.local.yaml down

# View logs
docker compose -f docker-compose.local.yaml logs -f

# View specific service logs
docker compose -f docker-compose.local.yaml logs -f app

# Restart a service
docker compose -f docker-compose.local.yaml restart app

# Rebuild containers
docker compose -f docker-compose.local.yaml up -d --build

# Stop and remove everything (including volumes)
docker compose -f docker-compose.local.yaml down -v
```

### Laravel Commands

```bash
# Run artisan commands
docker compose -f docker-compose.local.yaml exec app php artisan [command]

# Examples:
docker compose -f docker-compose.local.yaml exec app php artisan migrate
docker compose -f docker-compose.local.yaml exec app php artisan db:seed
docker compose -f docker-compose.local.yaml exec app php artisan cache:clear
docker compose -f docker-compose.local.yaml exec app php artisan config:clear
docker compose -f docker-compose.local.yaml exec app php artisan queue:work

# Run tests
docker compose -f docker-compose.local.yaml exec app php artisan test

# Access container shell
docker compose -f docker-compose.local.yaml exec app sh

# Run Composer commands
docker compose -f docker-compose.local.yaml exec app composer install
docker compose -f docker-compose.local.yaml exec app composer update
```

### Database Commands

```bash
# Connect to PostgreSQL (from inside container)
docker compose -f docker-compose.local.yaml exec postgres psql -U teren_user -d teren_app

# Connect from Windows host
psql -h localhost -p 5433 -U teren_user -d teren_app

# Backup database
docker compose -f docker-compose.local.yaml exec postgres pg_dump -U teren_user teren_app > backup.sql

# Restore database
docker compose -f docker-compose.local.yaml exec -T postgres psql -U teren_user teren_app < backup.sql

# Reset database
docker compose -f docker-compose.local.yaml exec app php artisan migrate:fresh --seed
```

## pgAdmin Setup

1. Open http://localhost:5050
2. Login: `admin@local.dev` / `admin`
3. Add Server:
   - **General Tab:**
     - Name: `Teren Local`
   - **Connection Tab:**
     - Host: `postgres`
     - Port: `5432`
     - Database: `teren_app`
     - Username: `teren_user`
     - Passwo

**External Connection:** To connect from your Windows machine (e.g., DBeaver, pgAdmin desktop), use:
- Host: `localhost`
- Port: `5433` (not 5432)
- Database: `teren_app`
- Username: `teren_user`
- Password: `local_password`rd: `local_password`
4. Click Save

## Mailpit - Email Testing

All emails sent by the application are caught by Mailpit.

- Access: http://localhost:8025
- View all emails in the web interface
- Test email sending:

```bash
docker compose -f docker-compose.local.yaml exec app php artisan tinker
# In tinker:
Mail::raw('Test email', function($msg) {
    $msg->to('test@example.com')->subject('Test');
});
```

## Portainer Setup

1. Open http://localhost:9000
2. On first visit, create admin account
3. Select "Docker" environment
4. Click "Connect"

Use Portainer to:
- View and manage containers
- Check logs
- Execute commands in containers
- Monitor resource usage

## Development Workflow

### Frontend Development

The local setup supports live reloading:

```bash
# Run Vite dev server (outside Docker)
npm run dev

# Or inside Docker
docker compose -f docker-compose.local.yaml exec app npm run dev
```

Access: http://localhost:8080

### Code Changes

All code changes are automatically reflected because the source code is mounted as a volume:

```yaml
volumes:
  - ./:/var/www  # Live code mounting
```

### Queue Workers

Queue workers are running via Supervisor inside the container. To restart:

```bash
# Restart queue workers
docker compose -f docker-compose.local.yaml exec app supervisorctl restart all

# Check status
docker compose -f docker-compose.local.yaml exec app supervisorctl status

# View worker logs
docker compose -f docker-compose.local.yaml exec app tail -f storage/logs/worker.log
```

## Troubleshooting

### Port Already in Use

If you get "port is already allocated" error:

```bash
# Windows - Find process using port
netstat -ano | findstr :8080

# Kill process by PID
taskkill /PID <PID> /F

# Or change port in docker-compose.local.yaml
ports:
  - "8081:80"  # Change 8080 to 8081
```

### Container Won't Start

```bash
# Check logs
docker compose -f docker-compose.local.yaml logs app

# Rebuild containers
docker compose -f docker-compose.local.yaml down
docker compose -f docker-compose.local.yaml up -d --build
```

### Permission Errors (Linux/Mac)

```bash
# Fix storage permissions
docker compose -f docker-compose.local.yaml exec app chown -R www:www /var/www/storage
docker compose -f docker-compose.local.yaml exec app chmod -R 775 /var/www/storage
```

### Database Connection Failed

```bash
# Check if PostgreSQL is running
docker compose -f docker-compose.local.yaml ps postgres

# Check logs
docker compose -f docker-compose.local.yaml logs postgres

# Restart PostgreSQL
docker compose -f docker-compose.local.yaml restart postgres
```

### Clear All Data and Start Fresh

```bash
# Stop and remove everything
docker compose -f docker-compose.local.yaml down -v

# Remove images
docker compose -f docker-compose.local.yaml down --rmi all

# Start fresh
docker compose -f docker-compose.local.yaml up -d --build

# Re-initialize
docker compose -f docker-compose.local.yaml exec app php artisan key:generate
docker compose -f docker-compose.local.yaml exec app php artisan migrate:fresh --seed
```

## Performance Tips

### Windows Performance

If using WSL2 (recommended):

1. Clone repo inside WSL2 filesystem, not Windows filesystem
2. Use WSL2 terminal for commands
3. Enable WSL2 integration in Docker Desktop settings

### Mac Performance

1. Enable VirtioFS in Docker Desktop settings
2. Disable file watching if not needed
3. Use Docker volumes for vendor directories:

```yaml
volumes:
  - ./:/var/www
  - /var/www/vendor  # Anonymous volume for vendor
  - /var/www/node_modules  # Anonymous volume for node_modules
```

## Testing Production-Like Setup

To test the production VPN setup locally (advanced):

1. Enable WireGuard in `docker-compose.yaml.example`
2. Change all `10.13.13.1` bindings to `127.0.0.1`
3. Test SSL with self-signed certificates

## Differences from Production

| Feature | Local | Production |
|---------|-------|------------|
| **VPN** | No VPN | WireGuard required |
| **Port** | :8080 | :80/:443 |
| **SSL** | No SSL | Let's Encrypt |
| **Debug** | Enabled | Disabled |
| **Emails** | Mailpit | Real SMTP |
| **Logs** | Debug level | Error level |
| **Code** | Live mount | Built into image |

## Next Steps

After testing locally:

1. Review `docker-compose.yaml.example` for production
2. Follow `DEPLOYMENT_GUIDE.md` for VPS setup
3. Configure WireGuard VPN
4. Deploy to production

## Useful Resources

- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [Laravel Docker Documentation](https://laravel.com/docs/deployment)
- [PostgreSQL Docker](https://hub.docker.com/_/postgres)
- [Mailpit Documentation](https://github.com/axllent/mailpit)