tfm_ainventory/DEPLOYMENT.md

TFM aInventory — Unified Deployment & Operations Guide

Audience: System administrators, DevOps teams, Site managers Version: 1.14.6 (Phase 6) Last Updated: 2026-04-23

---

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.

Both modes share the same configuration file (inventory.env) and operational scripts.

---

2. Prerequisites

2.1 Minimum Hardware Requirements

• 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

2.2 Software Requirements

• Docker Mode: Docker 24.0+ and Docker Compose 2.0+
• Standalone Mode: Python 3.12+, Node.js 20+, npm 10+

---

3. Quick Start

3.1 Step 1: Prepare Environment

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)

chmod +x deploy.sh
./deploy.sh production

• 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)

chmod +x start_server.sh
./start_server.sh

• Access: http://localhost:8917 (Frontend), http://localhost:8916 (API)

---

4. Configuration Reference (inventory.env)

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)

---

5. Operations & Health Monitoring

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.2 Logging

• Docker: docker-compose logs -f [service_name]
• Standalone: tail -f logs/backend.log and tail -f logs/frontend.log

5.3 Automated Backups

Automated backups are configured via cron:

sudo bash config/backup-cron.sh

• Daily: 2 AM (30-day retention)
• Weekly: 3 AM Sundays (90-day retention)
• Manual Backup: ./scripts/backup.sh manual

---

6. Disaster Recovery & Troubleshooting

6.1 Restore Procedure

# Docker mode
./scripts/restore.sh backups/inventory-2026-04-23.tar.gz --validate

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

---

Next Steps: See USER_GUIDE.md for application usage or PROJECT_ARCHITECTURE.md for technical deep-dives.