feat(6): phase 6 plan 02 - operational runbook and documentation

- Created OPERATIONAL_RUNBOOK.md: comprehensive step-by-step procedures for both Docker and Standalone deployment modes covering deployment, daily ops, troubleshooting, backup/restore, disaster recovery, scaling, and updates - Created HEALTH_MONITORING_CHECKLIST.md: daily/weekly/monthly health check procedures with alert thresholds and quick troubleshooting reference - Created DISASTER_RECOVERY_PLAN.md: detailed procedures for 6 failure scenarios (database corruption, hardware failure, data center failure, app crash, disk full, network isolation) with RTO/RPO targets - Created CONFIGURATION_REFERENCE.md: complete documentation of all inventory.env parameters for both deployment modes with common scenarios and troubleshooting - Created EMERGENCY_PROCEDURES.md: quick-reference incident response playbook with 7 critical scenarios, decision tree, escalation path, and printable cheat sheet - Created scripts/backup.sh: automated backup script supporting both Docker and Standalone with integrity verification and retention management - Created scripts/restore.sh: restore script with triple confirmation, safety backups, and validation tests for both deployment modes - Created config/backup-cron.sh: installer for daily/weekly automated backup cron jobs (2 AM daily, 3 AM Sunday) All documentation covers dual-deployment modes with shared configuration files. Documentation is operator-ready with copy-paste commands and clear expected outputs.
2026-04-22 18:25:32 +03:00
parent be3555d7cd
commit fc149184e9
14 changed files with 3166 additions and 260 deletions
--- a/docs/CONFIGURATION_REFERENCE.md
+++ b/docs/CONFIGURATION_REFERENCE.md
@@ -0,0 +1,472 @@
+# Configuration Reference
+
+**Purpose**: Document all configuration parameters for both Docker and Standalone deployment modes.  
+**Shared Config**: inventory.env (used by both modes)  
+**Last Updated**: 2026-04-22
+
+---
+
+## Overview
+
+Both Docker and Standalone deployment modes use the same `inventory.env` configuration file. All parameters are documented here with defaults, ranges, and examples.
+
+---
+
+## inventory.env Parameters
+
+### Network & Server Configuration
+
+```bash
+# Backend API server port (Docker exposed on this port)
+BACKEND_PORT=8000
+# Default: 8000
+# Range: 1024-65535
+# Common: 8000, 8080, 5000
+
+# Frontend server port
+FRONTEND_PORT=3000
+# Default: 3000
+# Range: 1024-65535
+# Common: 3000, 3001, 8888
+
+# Host binding (0.0.0.0 = all interfaces, 127.0.0.1 = localhost only)
+BACKEND_HOST=0.0.0.0
+FRONTEND_HOST=0.0.0.0
+# Use 127.0.0.1 for development only, 0.0.0.0 for production
+
+# External server address (for CORS and frontend API calls)
+SERVER_URL=http://localhost:8000
+# Example for production: http://inventory.example.com:8000
+# Or with HTTPS: https://inventory.example.com
+```
+
+### Security & Authentication
+
+```bash
+# JWT secret key for API authentication (generate with: openssl rand -hex 32)
+JWT_SECRET_KEY=your-generated-hex-string-here
+# Min length: 32 characters
+# IMPORTANT: Change this in production
+# Generation: openssl rand -hex 32
+
+# Algorithm for JWT signing
+JWT_ALGORITHM=HS256
+# Default: HS256
+# Options: HS256, HS384, HS512
+
+# LDAP server configuration (optional, for enterprise auth)
+LDAP_SERVER=ldap.example.com
+LDAP_PORT=389
+LDAP_BIND_DN=cn=admin,dc=example,dc=com
+LDAP_BASE_DN=ou=users,dc=example,dc=com
+LDAP_USE_SSL=false
+# Set to empty/false to disable LDAP (use local auth only)
+
+# Password hashing iterations (PBKDF2)
+PASSWORD_HASH_ITERATIONS=100000
+# Default: 100000
+# Higher = more secure but slower
+```
+
+### Database Configuration
+
+```bash
+# Database file location
+DATABASE_URL=sqlite:///./data/inventory.db
+# For Docker: Use /app/data/inventory.db inside container
+# For Standalone: Use ./data/inventory.db
+
+# Database connection pool size
+DB_POOL_SIZE=10
+# Default: 10
+# Increase for 10+ concurrent users
+# Docker: Keep <20 due to SQLite single-writer
+# Standalone: Keep <15
+
+# Database WAL mode (write-ahead logging, improves concurrency)
+DATABASE_JOURNAL_MODE=WAL
+# Default: WAL
+# Options: WAL, DELETE
+# WAL = better concurrency, more disk space
+# DELETE = less disk, slower writes
+```
+
+### AI Provider Configuration
+
+```bash
+# Primary AI provider (gemini or claude)
+PRIMARY_AI_PROVIDER=gemini
+# Options: gemini, claude
+# Default: gemini (more cost-effective)
+
+# Google Gemini API key (for label extraction)
+GEMINI_API_KEY=your-api-key-here
+# Get from: https://aistudio.google.com/app/apikeys
+# Leave empty to disable Gemini
+
+# Anthropic Claude API key (for label extraction)
+CLAUDE_API_KEY=your-api-key-here
+# Get from: https://console.anthropic.com/
+# Leave empty to disable Claude
+
+# AI model selection
+GEMINI_MODEL=gemini-2.0-flash
+CLAUDE_MODEL=claude-3-5-sonnet-20241022
+# Use latest stable versions available
+
+# AI image processing mode (box or standard)
+AI_BOX_DISCOVERY_MODE=false
+# Set to true for enhanced box label detection
+# Default: false (standard detection)
+
+# AI request timeout (seconds)
+AI_REQUEST_TIMEOUT=30
+# Default: 30 seconds
+# Increase for slower connections
+```
+
+### Logging Configuration
+
+```bash
+# Log level for backend
+LOG_LEVEL=INFO
+# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
+# DEBUG = verbose (development)
+# INFO = normal (production)
+# ERROR = minimal output
+
+# Log file location
+LOG_FILE=./logs/backend.log
+# For Docker: /app/logs/backend.log
+# For Standalone: ./logs/backend.log
+
+# Maximum log file size before rotation
+LOG_MAX_SIZE=10485760  # 10MB
+# Default: 10MB
+
+# Number of backup log files to keep
+LOG_BACKUP_COUNT=5
+# Default: 5 files
+```
+
+### CORS & Network Security
+
+```bash
+# Allowed origins for CORS (comma-separated)
+ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8906
+# Add additional IPs/domains here
+# Example for production:
+# ALLOWED_ORIGINS=https://inventory.example.com,https://app.example.com
+
+# Extra allowed origins (for VPN/Tailscale IPs)
+EXTRA_ALLOWED_ORIGINS=10.0.0.0/8
+# Supports IP addresses, CIDR ranges, domain names
+# Comma-separated for multiple entries
+
+# Enable CORS credentials (cookies, auth headers)
+CORS_CREDENTIALS=true
+# Default: true
+```
+
+### Feature Flags
+
+```bash
+# Enable AI-powered label extraction
+ENABLE_AI_EXTRACTION=true
+# Default: true
+# Set to false if no API keys configured
+
+# Enable offline sync
+ENABLE_OFFLINE_SYNC=true
+# Default: true
+# Keep enabled for field operations
+
+# Enable QR code scanning
+ENABLE_QR_SCANNING=true
+# Default: true
+# Core feature, always enabled
+
+# Enable box labeling system
+ENABLE_BOX_LABELS=true
+# Default: true
+# v1.5.0+ feature
+```
+
+### Performance & Optimization
+
+```bash
+# API request timeout (seconds)
+REQUEST_TIMEOUT=30
+# Default: 30 seconds
+# Increase if experiencing slow connections
+
+# Database query timeout (seconds)
+DATABASE_TIMEOUT=10
+# Default: 10 seconds
+# Increase for large datasets (10K+ items)
+
+# Backend worker threads
+WORKERS=4
+# For Standalone mode (if using Gunicorn)
+# Default: 4
+# Increase for high concurrency
+# Formula: (2 x CPUs) + 1
+
+# Frontend build optimization
+NEXT_PUBLIC_OPTIMIZE_IMAGES=true
+# Default: true
+# Enable for production deployments
+```
+
+### Deployment & Version
+
+```bash
+# Application version (auto-managed)
+VERSION=1.14.6
+# Updated by: scripts/save_version.py
+# Do not edit manually
+
+# Environment (development, staging, production)
+ENVIRONMENT=production
+# Options: development, staging, production
+# Affects logging, error messages, CORS strictness
+
+# Docker image tag (if using docker-compose)
+DOCKER_IMAGE_TAG=latest
+# Options: latest, stable, v1.14.6, custom-tag
+```
+
+### Backup & Operations
+
+```bash
+# Backup directory (relative path)
+BACKUP_DIR=./backups
+# Default: ./backups
+# For Docker: /app/backups (persisted volume)
+
+# Backup retention (days)
+BACKUP_RETENTION_DAILY=30
+BACKUP_RETENTION_WEEKLY=90
+# Default: 30 days (daily), 90 days (weekly)
+
+# Enable automated backups (cron)
+ENABLE_CRON_BACKUPS=true
+# Default: true
+# Requires: sudo bash config/backup-cron.sh
+```
+
+---
+
+## Docker-Specific Configuration
+
+### docker-compose.yml
+
+These are handled by the deployment but documented for reference:
+
+```yaml
+# Backend service
+backend:
+  environment:
+    - DATABASE_URL=sqlite:////app/data/inventory.db
+    - LOG_FILE=/app/logs/backend.log
+    - PYTHONUNBUFFERED=1
+  ports:
+    - "${BACKEND_PORT}:8000"
+  volumes:
+    - ./data:/app/data
+    - ./config:/app/config
+    - ./logs:/app/logs
+
+# Frontend service
+frontend:
+  environment:
+    - NEXT_PUBLIC_API_URL=http://localhost:${BACKEND_PORT}
+  ports:
+    - "${FRONTEND_PORT}:3000"
+
+# Proxy service (Caddy)
+proxy:
+  ports:
+    - "8909:8909"  # HTTPS proxy
+  volumes:
+    - ./data/caddy_data:/data
+    - ./data/caddy_config:/config
+```
+
+---
+
+## Standalone-Specific Configuration
+
+### Environment Variables for start_server.sh
+
+The script reads from `inventory.env` and sets up:
+
+```bash
+# Python environment
+PYTHONUNBUFFERED=1  # Direct logging output
+PYTHONPATH=./backend
+
+# Node environment
+NODE_ENV=production
+
+# Paths
+BACKEND_DIR=./backend
+FRONTEND_DIR=./frontend
+DATA_DIR=./data
+LOGS_DIR=./logs
+```
+
+---
+
+## Configuration Validation
+
+### Pre-Deployment Checks
+
+Run these to validate configuration before starting services:
+
+```bash
+# Docker mode
+./deploy.sh validate
+
+# Standalone mode
+python3 backend/config_manager.py --validate
+
+# Manual checks
+[ -f inventory.env ] && echo "✓ inventory.env exists"
+[ -d data ] && echo "✓ data directory exists"
+[ -d logs ] && echo "✓ logs directory exists"
+openssl rand -hex 32 > /dev/null && echo "✓ OpenSSL available"
+```
+
+---
+
+## Common Configuration Scenarios
+
+### Scenario 1: Local Development
+
+```bash
+BACKEND_PORT=8000
+FRONTEND_PORT=3000
+BACKEND_HOST=127.0.0.1
+JWT_SECRET_KEY=dev-key-not-for-production
+LOG_LEVEL=DEBUG
+ENVIRONMENT=development
+ENABLE_AI_EXTRACTION=false  # Save API costs
+```
+
+### Scenario 2: Single-Server Production
+
+```bash
+BACKEND_PORT=8000
+FRONTEND_PORT=3000
+BACKEND_HOST=0.0.0.0
+SERVER_URL=https://inventory.example.com
+JWT_SECRET_KEY=<generate-with-openssl>
+LOG_LEVEL=INFO
+ENVIRONMENT=production
+PRIMARY_AI_PROVIDER=gemini
+GEMINI_API_KEY=<your-api-key>
+```
+
+### Scenario 3: High Concurrency (Standalone)
+
+```bash
+DB_POOL_SIZE=15
+WORKERS=8  # (2 x CPUs) + 1
+REQUEST_TIMEOUT=45
+DATABASE_TIMEOUT=15
+LOG_LEVEL=WARNING  # Reduce I/O for performance
+```
+
+### Scenario 4: LDAP Enterprise Auth
+
+```bash
+LDAP_SERVER=ldap.company.com
+LDAP_PORT=389
+LDAP_BIND_DN=cn=admin,dc=company,dc=com
+LDAP_BASE_DN=ou=people,dc=company,dc=com
+LDAP_USE_SSL=true
+# Users login with their LDAP credentials
+```
+
+---
+
+## Troubleshooting Configuration Issues
+
+### Port Already in Use
+
+```bash
+# Find process using port
+lsof -i :8000
+netstat -tuln | grep 8000
+
+# Solution: Change BACKEND_PORT or kill process
+```
+
+### JWT Secret Not Set
+
+```bash
+# Generate new secret
+openssl rand -hex 32
+
+# Add to inventory.env
+echo "JWT_SECRET_KEY=$(openssl rand -hex 32)" >> inventory.env
+```
+
+### Database Connection Error
+
+```bash
+# Check database file exists
+ls -la data/inventory.db
+
+# Check permissions
+chmod 644 data/inventory.db
+
+# Reset if corrupted
+rm data/inventory.db
+# (Backup will be restored on next startup)
+```
+
+### LDAP Authentication Failing
+
+```bash
+# Test LDAP connection
+ldapsearch -x -H ldap://ldap.company.com:389 -D "cn=admin,dc=company,dc=com"
+
+# Check configuration matches LDAP schema
+# May need to adjust LDAP_BASE_DN or LDAP_BIND_DN
+```
+
+---
+
+## Environment Variable Precedence
+
+Configuration is loaded in this order:
+
+1. Defaults (hardcoded in code)
+2. `inventory.env` file
+3. OS environment variables (override)
+4. Command-line arguments (highest priority)
+
+Example override:
+```bash
+BACKEND_PORT=9000 ./deploy.sh production
+```
+
+---
+
+## Security Best Practices
+
+- [ ] Generate unique JWT_SECRET_KEY for each environment
+- [ ] Never commit `inventory.env` to git (add to `.gitignore`)
+- [ ] Use HTTPS in production (configure reverse proxy)
+- [ ] Rotate LDAP passwords quarterly
+- [ ] Limit ALLOWED_ORIGINS to known domains
+- [ ] Use strong JWT_ALGORITHM (HS256 minimum)
+- [ ] Monitor LOG_LEVEL in production (avoid DEBUG)
+
+---
+
+**Version**: 1.0  
+**Last Updated**: 2026-04-22  
+**Maintained By**: Operations Team