initialization

2026-10-07 01:16:57 +02:00
commit 9ff09693ed
@@ -0,0 +1,303 @@
+# 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
+```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:
+      - ./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!