bede/tfm_ainventory
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(07-04): rewrite DEPLOYMENT.md for Phase 7 config structure

Browse Source
This commit is contained in:
Daniel Bedeleanu
2026-04-23 12:53:41 +03:00
parent 0c6f571aa7
commit 22343941bd
1 changed files with 134 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

195
DEPLOYMENT.md
View File

@@ -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
[D-08] The `config/` directory is the single source of truth for all application settings.
### 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) |
### 3.2 Setup Configuration
1. **Clone and enter repository:**
```bash
git clone <repository-url> tfm-inventory
cd tfm-inventory
cp inventory.env.example inventory.env
# Generate a secure JWT secret
openssl rand -hex 32 # Copy this to JWT_SECRET_KEY in inventory.env
# Customize other settings (ports, AI keys, LDAP)
nano inventory.env
```
### 3.2 Step 2: Deployment Mode
#### Option A: Docker Deployment (Recommended for Production)
2. **Initialize config from examples:**
```bash
chmod +x deploy.sh
./deploy.sh production
# Copy all examples to actual config files
for f in config/*.yaml.example; do cp "$f" "${f%.example}"; done
```
- **Access**: http://localhost:8917 (Frontend), http://localhost:8916/docs (API)
- **HTTPS**: https://localhost:8909 (via Caddy proxy)
#### Option B: Standalone Deployment (Recommended for Development/Low-Resource)
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.
4. **Generate JWT Secret:**
```bash
chmod +x start_server.sh
./start_server.sh
# Generate a 64-character hex secret
openssl rand -hex 32
# Copy this value to jwt_secret_key in config/secrets.yaml
```
- **Access**: http://localhost:8917 (Frontend), http://localhost:8916 (API)
[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.