From 22343941bdd69ef810e7c063c49511a9bf2acbdc Mon Sep 17 00:00:00 2001 From: Daniel Bedeleanu Date: Thu, 23 Apr 2026 12:53:41 +0300 Subject: [PATCH] docs(07-04): rewrite DEPLOYMENT.md for Phase 7 config structure --- DEPLOYMENT.md | 205 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 134 insertions(+), 71 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 050e5e10..067d4753 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -1,15 +1,15 @@ # TFM aInventory — Unified Deployment & Operations Guide **Audience**: System administrators, DevOps teams, Site managers -**Version**: 1.14.6 (Phase 6) -**Last Updated**: 2026-04-23 +**Version**: 1.15.0 (Phase 7 - Config Consolidation) +**Last Updated**: 2026-05-15 --- ## 1. Overview -TFM aInventory is a unified inventory management system supporting web administration, field scanning (QR/barcode), AI-powered label extraction, and offline sync. This guide provides instructions for both **Docker** and **Standalone** deployment modes. +TFM aInventory is a unified inventory management system supporting web administration, field scanning (QR/barcode), AI-powered label extraction, and offline sync. -Both modes share the same configuration file (`inventory.env`) and operational scripts. +[D-07] Since Phase 7, the application uses a consolidated configuration structure in the `config/` directory. The legacy `inventory.env` file is deprecated in favor of YAML-based configuration for better structure and validation. --- @@ -19,77 +19,120 @@ Both modes share the same configuration file (`inventory.env`) and operational s - **OS**: Ubuntu 22.04 LTS or similar Linux distribution - **RAM**: 2GB minimum (4GB recommended for production) - **Disk**: 10GB free space (50GB recommended for logs/backups) -- **Network**: Internet access (first-time setup), Ports 8916 (Backend) & 8917 (Frontend) available +- **Network**: Internet access (first-time setup), Ports 8000 (Backend) & 3000 (Frontend) available ### 2.2 Software Requirements - **Docker Mode**: Docker 24.0+ and Docker Compose 2.0+ - **Standalone Mode**: Python 3.12+, Node.js 20+, npm 10+ +- **All Modes**: Python 3.12+ (for deployment scripts) --- -## 3. Quick Start +## 3. Configuration -### 3.1 Step 1: Prepare Environment -```bash -git clone tfm-inventory -cd tfm-inventory -cp inventory.env.example inventory.env +[D-08] The `config/` directory is the single source of truth for all application settings. -# Generate a secure JWT secret -openssl rand -hex 32 # Copy this to JWT_SECRET_KEY in inventory.env +### 3.1 Configuration Files +| File | Description | +|------|-------------| +| `config/backend.yaml` | Backend API, database, and AI settings | +| `config/frontend.yaml` | Frontend UI and connection settings | +| `config/network.yaml` | Port assignments and SSL configuration | +| `config/docker.yaml` | Docker resource limits and volume drivers | +| `config/secrets.yaml` | Sensitive keys (API keys, JWT secrets) | -# Customize other settings (ports, AI keys, LDAP) -nano inventory.env -``` +### 3.2 Setup Configuration +1. **Clone and enter repository:** + ```bash + git clone tfm-inventory + cd tfm-inventory + ``` -### 3.2 Step 2: Deployment Mode +2. **Initialize config from examples:** + ```bash + # Copy all examples to actual config files + for f in config/*.yaml.example; do cp "$f" "${f%.example}"; done + ``` -#### Option A: Docker Deployment (Recommended for Production) -```bash -chmod +x deploy.sh -./deploy.sh production -``` -- **Access**: http://localhost:8917 (Frontend), http://localhost:8916/docs (API) -- **HTTPS**: https://localhost:8909 (via Caddy proxy) +3. **Customize your settings:** + - Edit `config/backend.yaml` for application behavior. + - Edit `config/network.yaml` for port assignments. + - Edit `config/secrets.yaml` with your API keys. -#### Option B: Standalone Deployment (Recommended for Development/Low-Resource) -```bash -chmod +x start_server.sh -./start_server.sh -``` -- **Access**: http://localhost:8917 (Frontend), http://localhost:8916 (API) +4. **Generate JWT Secret:** + ```bash + # Generate a 64-character hex secret + openssl rand -hex 32 + # Copy this value to jwt_secret_key in config/secrets.yaml + ``` + +[D-06] **Environment Variable Overrides**: System environment variables take precedence over YAML config values. This is useful for Docker overrides or CI/CD pipelines. --- -## 4. Configuration Reference (`inventory.env`) +## 4. Quick Start -| Category | Variable | Default | Description | -|----------|----------|---------|-------------| -| **Network** | `BACKEND_PORT` | 8916 | Port for FastAPI backend | -| | `FRONTEND_PORT` | 8917 | Port for Next.js frontend | -| **Security** | `JWT_SECRET_KEY` | - | **REQUIRED**: Generate with `openssl rand -hex 32` | -| | `LDAP_SERVER` | - | LDAP server for enterprise auth (Optional) | -| **AI** | `PRIMARY_AI_PROVIDER` | `gemini` | `gemini` or `claude` | -| | `GEMINI_API_KEY` | - | Required if using Gemini | -| | `CLAUDE_API_KEY` | - | Required if using Claude | -| **Data** | `DATA_DIR` | `./data` | Persistent data location | -| | `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | -| **Backups** | `BACKUP_RETENTION_DAILY` | 30 | Daily backup retention (days) | +### 4.1 Option A: Docker Deployment (Recommended) +```bash +python3 scripts/deploy.py production +``` +- **Access**: http://localhost:3000 (Frontend), http://localhost:8000/docs (API) +- **HTTPS**: https://localhost:8919 (via Caddy proxy) + +### 4.2 Option B: Standalone Deployment +```bash +python3 scripts/run_standalone.py +``` +- **Access**: http://localhost:3000 (Frontend), http://localhost:8000 (API) --- -## 5. Operations & Health Monitoring +## 5. Deployment Modes -### 5.1 Health Checks -- **Docker**: `docker-compose ps` (All services should be `healthy`) -- **Standalone**: `ps aux | grep -E "(uvicorn|next)"` -- **API Health**: `curl http://localhost:8916/health` +### 5.1 Docker Deployment (scripts/deploy.py) +The `deploy.py` script manages the Docker lifecycle, including configuration validation and health checks. -### 5.2 Logging -- **Docker**: `docker-compose logs -f [service_name]` -- **Standalone**: `tail -f logs/backend.log` and `tail -f logs/frontend.log` +**Usage:** +```bash +python3 scripts/deploy.py [production|staging|development] [--rebuild] +``` -### 5.3 Automated Backups +- **Production**: Optimized images, resource limits enforced. +- **Staging**: Mirror of production for testing. +- **Development**: Hot-reloading enabled, debug logging. + +### 5.2 Standalone Deployment (scripts/run_standalone.py) +For environments without Docker, use the standalone runner. It manages both backend and frontend processes. + +**Usage:** +```bash +python3 scripts/run_standalone.py [--backend-only|--frontend-only] +``` + +### 5.3 Systemd Service Installation +To run aInventory as a background service on Linux: + +```bash +sudo python3 scripts/install_service.py [--user=www-data] +``` + +- **Start**: `sudo systemctl start ainventory` +- **Status**: `sudo systemctl status ainventory` +- **Logs**: `journalctl -u ainventory -f` + +--- + +## 6. Backup & Export + +### 6.1 Production Export (scripts/export_prod.py) +Create a production-ready bundle including data and sanitized configuration. + +```bash +python3 scripts/export_prod.py [--output=/path/to/backup.tar.gz] [--include-logs] +``` +*Note: actual secrets in `secrets.yaml` are excluded for security; config examples are included.* + +### 6.2 Automated Backups Automated backups are configured via cron: ```bash sudo bash config/backup-cron.sh @@ -100,30 +143,50 @@ sudo bash config/backup-cron.sh --- -## 6. Disaster Recovery & Troubleshooting +## 7. Operations & Health Monitoring -### 6.1 Restore Procedure -```bash -# Docker mode -./scripts/restore.sh backups/inventory-2026-04-23.tar.gz --validate +### 7.1 Health Checks +- **Docker**: `docker compose ps` (All services should be `running` and `healthy`) +- **API Health**: `curl http://localhost:8000/health` +- **Frontend Health**: `curl -f http://localhost:3000/` -# Standalone mode -./scripts/restore.sh backups/inventory-2026-04-23.tar.gz -``` - -### 6.2 Common Issues -- **Port Already in Use**: Check `lsof -i :8916` and kill or change port in `inventory.env`. -- **Database Locked**: Restart backend service. -- **HTTPS Warning**: Caddy uses self-signed certs for local HTTPS; click "Proceed anyway". -- **Out of Space**: Clean old backups in `./backups/`. +### 7.2 Logging +- **Docker**: `docker compose logs -f [backend|frontend|proxy]` +- **Standalone**: Check files in `./logs/` directory. --- -## 7. Performance & Scaling -- **Concurrent Users**: Optimized for ~5 concurrent users. -- **Item Capacity**: Handles 10K+ items on standard SSD hardware. -- **Optimization**: Use `LOG_LEVEL=WARNING` in production to reduce I/O. +## 8. Security + +- **secrets.yaml**: This file is excluded from Git via `.gitignore`. Never commit it. +- **JWT Secrets**: Always rotate `jwt_secret_key` before production deployment. +- **File Permissions**: The `deploy.py` and `install_service.py` scripts attempt to set restrictive permissions on config files. +- **Read-Only Mounts**: In Docker mode, the `config/` directory is mounted as read-only (`:ro`) to prevent the container from modifying its own configuration. --- -**Next Steps**: See `USER_GUIDE.md` for application usage or `PROJECT_ARCHITECTURE.md` for technical deep-dives. +## 9. Troubleshooting + +- **Missing Config**: Ensure you copied `.yaml.example` files to `.yaml`. +- **Invalid YAML**: Check your config files with a YAML validator. +- **Port Conflict**: Update `config/network.yaml` if ports 8000 or 3000 are in use. +- **Permission Denied**: Run scripts with `sudo` if they need to write to system paths (like systemd). +- **AI Failures**: Verify your API keys in `config/secrets.yaml` and check `backend.log`. + +--- + +## 10. Migration from inventory.env + +[D-04] To migrate from a legacy `inventory.env` file: + +1. Locate your old `inventory.env`. +2. Map the variables to the new YAML files: + - `BACKEND_PORT` -> `config/network.yaml` (`backend_port`) + - `JWT_SECRET_KEY` -> `config/secrets.yaml` (`jwt_secret_key`) + - `GEMINI_API_KEY` -> `config/secrets.yaml` (`gemini_api_key`) + - `DATA_DIR` -> `config/backend.yaml` (`application.data_dir`) +3. Delete the old `inventory.env` once migration is verified. + +--- + +**Next Steps**: See `config/README.md` for detailed configuration reference or `README.md` for general project overview.