130 lines
4.1 KiB
Markdown
130 lines
4.1 KiB
Markdown
# 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.
|