# 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
```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)
```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)

#### 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. 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:
```bash
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
```bash
# 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.