tfm_ainventory/DEPLOYMENT.md

TFM aInventory — Unified Deployment & Operations Guide

Audience: System administrators, DevOps teams, Site managers 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.

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

---

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

[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:

   git clone <repository-url> tfm-inventory
   cd tfm-inventory
   

2. Initialize config from examples:

   # Copy all examples to actual config files
   for f in config/*.yaml.example; do cp "$f" "${f%.example}"; done
   

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:

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

4.1 Option A: Docker Deployment (Recommended)

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

python3 scripts/run_standalone.py

• Access: http://localhost:3000 (Frontend), http://localhost:8000 (API)

---

5. Deployment Modes

5.1 Docker Deployment (scripts/deploy.py)

The deploy.py script manages the Docker lifecycle, including configuration validation and health checks.

Usage:

python3 scripts/deploy.py [production|staging|development] [--rebuild]

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

python3 scripts/run_standalone.py [--backend-only|--frontend-only]

5.3 Systemd Service Installation

To run aInventory as a background service on Linux:

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.

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:

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

---

7. Operations & Health Monitoring

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/

7.2 Logging

• Docker: docker compose logs -f [backend|frontend|proxy]
• Standalone: Check files in ./logs/ directory.

---

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.

---

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.