pw-generator/DEPLOYMENT.md

Deployment Guide

Quick Start

1. Installation

# Make installation script executable
chmod +x install.sh

# Run installation
./install.sh

2. Development Server

# 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

<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

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

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:

cp docker-compose.example.yml docker-compose.yml

Then adapt the local values as needed:

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

# 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:

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:

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

# 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

# Monitor application logs
tail -f logs/app.log

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

Performance Optimization

# 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"

composer dump-autoload

Error: "Permission denied on logs"

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:

APP_DEBUG=true
LOG_LEVEL=debug

Remember to disable debug mode in production!