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:**
   ```bash
   git clone <repository-url> tfm-inventory
   cd tfm-inventory
   ```

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

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
   # 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)
```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. Deployment Modes

### 5.1 Docker Deployment (scripts/deploy.py)
The `deploy.py` script manages the Docker lifecycle, including configuration validation and health checks.

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