pw-generator/DEPLOYMENT.md

# Deployment Guide

## Quick Start

### 1. Installation
```bash
# Make installation script executable
chmod +x install.sh

# Run installation
./install.sh
```

### 2. Development Server
```bash
# Start with Composer
composer start

# Or manually
php -S localhost:8080 -t public
```

### 3. Access Application
- **Web Interface**: http://localhost:8080
- **API Documentation**: http://localhost:8080/docs
- **Health Check**: http://localhost:8080/api/v1/health

## Production Deployment

### Apache Configuration
```apache
<VirtualHost *:80>
    ServerName passwords.yourdomain.com
    DocumentRoot /var/www/password-generator/public
    
    <Directory /var/www/password-generator/public>
        AllowOverride All
        Require all granted
    </Directory>
    
    # Security headers
    Header always set X-Content-Type-Options nosniff
    Header always set X-Frame-Options DENY
    Header always set X-XSS-Protection "1; mode=block"
</VirtualHost>
```

### Nginx Configuration
```nginx
server {
    listen 80;
    server_name passwords.yourdomain.com;
    root /var/www/password-generator/public;
    index index.php;
    
    # Security headers
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    add_header X-XSS-Protection "1; mode=block";
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    # Cache static assets
    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1M;
        add_header Cache-Control "public, immutable";
    }
}
```

### Docker Deployment
```dockerfile
FROM php:8.4-cli

WORKDIR /var/www/html

ENV APP_ENV=production \
    APP_DEBUG=false \
    PORT=8080

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        bash \
        ca-certificates \
        curl \
        git \
        unzip \
        pwgen \
        xkcdpass \
    && rm -rf /var/lib/apt/lists/*

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
COPY . /var/www/html/

RUN composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist \
    && mkdir -p logs \
    && chmod 755 logs \
    && cp -n .env.example .env

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
    CMD curl -fsS http://127.0.0.1:8080/ >/dev/null || exit 1

CMD ["php", "-S", "0.0.0.0:8080", "-t", "public"]
```

### Docker Compose
Use the example template as the base for a local override:

```bash
cp docker-compose.example.yml docker-compose.yml
```

Then adapt the local values as needed:

```yaml
services:
  password-generator:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      APP_ENV: production
      APP_DEBUG: "false"
      LOG_LEVEL: warning
      RATE_LIMIT: "120"
      CORS_ORIGIN: "https://yourdomain.com"
      CORS_METHODS: "GET,POST,OPTIONS"
      CORS_HEADERS: "Content-Type,Authorization"
    volumes:
      - ./.env:/var/www/html/.env:ro
      - ./logs:/var/www/html/logs
    restart: unless-stopped
```

## Environment Configuration

### Production Environment Variables
```bash
# Application
APP_ENV=production
APP_DEBUG=false
APP_NAME="Password Generator API"
APP_VERSION="2.0.0"
APP_PUBLIC_BASE_URL="https://passwords.example.com"

# Security
API_KEY_ENABLED=false
RATE_LIMIT=120

# CORS (adjust for your domain)
CORS_ORIGIN="https://yourdomain.com"
CORS_METHODS="GET,POST,OPTIONS"
CORS_HEADERS="Content-Type,Authorization"

# Logging
LOG_LEVEL=warning
LOG_PATH=logs/app.log
```

### Secure Production Baseline
Use local development values from `.env.example` and set deployment values explicitly in the production environment. The application does not assume a public-safe default; it expects a secure deployment configuration to be provided at runtime.

Production checklist:
- [ ] `APP_ENV=production`
- [ ] `APP_DEBUG=false`
- [ ] `LOG_LEVEL=warning` or `error`
- [ ] `CORS_ORIGIN` restricted to trusted frontend domains only
- [ ] `RATE_LIMIT` tuned for the production deployment and not left at dev defaults
- [ ] `require_https=true` enforced at the reverse proxy or load balancer
- [ ] TLS termination with HSTS and strict security headers in front of the PHP app
- [ ] Secrets and runtime hostnames stored outside the repository

Remaining production hardening risks:
- In-memory rate limiting is still single-instance only; multi-node deployments should use shared storage.
- CORS must remain an explicit allow-list and should not be widened to wildcard origins.
- Log aggregation and retention should be added for production operations.
- Browser-facing security headers should be applied at the edge layer whenever the app is public.

### Regenerate the OpenAPI File
The public OpenAPI document is generated from the live route registry and the configured public base URL. Regenerate it after route changes or deployment configuration changes:

```bash
composer generate:openapi
# or
php utils/generate-openapi.php
```

This updates `public/pwgenerator-swagger-spec.json` with the current public API contract.

### SSL/TLS Configuration
For production, always use HTTPS:

```nginx
server {
    listen 443 ssl http2;
    server_name passwords.yourdomain.com;
    
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;
    
    # ... rest of configuration
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name passwords.yourdomain.com;
    return 301 https://$server_name$request_uri;
}
```

## Monitoring and Maintenance

### Health Checks
```bash
# API health check
curl -f http://localhost:8080/api/v1/health || exit 1

# Test password generation
curl -X POST http://localhost:8080/api/v1/passwords/generate \
  -H "Content-Type: application/json" \
  -d '{"type":"high-entropy","count":1}' \
  | jq '.success'
```

### Log Monitoring
```bash
# Monitor application logs
tail -f logs/app.log

# Check for errors
grep -i error logs/app.log
```

### Performance Optimization
```bash
# Enable OPcache for PHP
echo "opcache.enable=1" >> /etc/php/8.1/apache2/conf.d/99-opcache.ini
echo "opcache.memory_consumption=128" >> /etc/php/8.1/apache2/conf.d/99-opcache.ini

# Restart Apache
systemctl restart apache2
```

## Security Considerations

1. **Rate Limiting**: Adjust `RATE_LIMIT` based on your needs
2. **CORS**: Configure `CORS_ORIGIN` for your domain only
3. **HTTPS**: Always use SSL/TLS in production
4. **Firewall**: Restrict access to necessary ports only
5. **Updates**: Keep PHP and dependencies updated
6. **Logs**: Monitor logs for suspicious activity

## Backup Strategy

### Files to Backup
- Configuration files (`.env`)
- Custom wordlists (if added)
- Application logs
- Web server configuration

### Database
This application is stateless and doesn't require database backups.

## Troubleshooting

### Common Issues

**Error: "Class not found"**
```bash
composer dump-autoload
```

**Error: "Permission denied on logs"**
```bash
chmod 755 logs/
chown www-data:www-data logs/
```

**Error: "CORS blocked"**
- Check `CORS_ORIGIN` in `.env`
- Ensure proper headers in web server config

**High Memory Usage**
- Enable OPcache
- Increase PHP memory limit if needed

### Debug Mode
For troubleshooting, enable debug mode:
```bash
APP_DEBUG=true
LOG_LEVEL=debug
```

Remember to disable debug mode in production!