chore: major codebase cleanup and documentation consolidation
This commit is contained in:
129
DEPLOYMENT.md
Normal file
129
DEPLOYMENT.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user