tfm_ainventory/docs/DEPLOYMENT_QUICKSTART.md

Deployment Quick Start Guide

Overview

This guide covers two deployment methods for TFM aInventory:

1. Docker Mode - Full containerized deployment using Docker Compose
2. Standalone Mode - Direct server startup without Docker

Both modes use the same configuration files and can be switched between freely.

---

Prerequisites

Minimum Requirements

• Ubuntu 22.04 LTS or similar Linux distro
• 2GB RAM
• 10GB free disk space

For Docker Mode

• Docker 24.0+ (docker --version)
• Docker Compose 2.0+ (docker-compose --version)

For Standalone Mode

• Python 3.12+ (python3 --version)
• Node.js 20+ (node --version)
• npm 10+ (npm --version)

---

Quick Start (Docker Mode)

Step 1: Prepare Environment

git clone <repository-url> tfm-inventory
cd tfm-inventory
cp inventory.env.template inventory.env

# Edit inventory.env to customize ports and settings
nano inventory.env

Step 2: Generate Secure Secret

# Generate a 32-byte hex string for JWT_SECRET_KEY
openssl rand -hex 32

# Copy the output and paste it into inventory.env as JWT_SECRET_KEY value

Step 3: Deploy with Docker

chmod +x deploy.sh
./deploy.sh production

The script will:

• Validate prerequisites (Docker, disk space, ports)
• Build Docker images
• Create necessary data directories
• Start all services in background
• Wait for health checks (max 60 seconds)
• Display access URLs and next steps

Step 4: Verify Access

Open your browser:

• Frontend: http://localhost:3000
• Backend API Docs: http://localhost:8000/docs
• HTTPS (Secure): https://localhost:8919

---

Quick Start (Standalone Mode)

Step 1: Prepare Environment

cd tfm-inventory
cp inventory.env.template inventory.env

# Edit configuration as needed
nano inventory.env

Step 2: Install Dependencies

# Backend dependencies
cd backend
pip install -r requirements.txt
cd ..

# Frontend dependencies
cd frontend
npm ci
npm run build
cd ..

Step 3: Start Servers

chmod +x start_server.sh
./start_server.sh

The script will:

• Check prerequisites (Python, Node.js, ports)
• Create data directories
• Install missing dependencies
• Initialize database if needed
• Start backend API server
• Start frontend web server

Step 4: Access the Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

---

Configuration

Key Settings in inventory.env

Variable	Default	Description
BACKEND_PORT	8000	Backend API port
FRONTEND_PORT	3000	Frontend web server port
JWT_SECRET_KEY	-	REQUIRED: Generate with openssl rand -hex 32
LOG_LEVEL	INFO	Log verbosity: DEBUG, INFO, WARNING, ERROR
DATA_DIR	./data	Data files location (database, certs, etc.)
LOGS_DIR	./logs	Log files location
AI_PROVIDER	-	Optional: gemini, claude (if API keys provided)
LDAP_SERVER	-	Optional: LDAP server for authentication

First-Time Setup

On first deployment:

1. Database is automatically initialized
2. Caddy HTTPS certificates are generated (may show browser warning on first access)
3. Default admin user may be created (check logs)

---

Switching Between Modes

Docker to Standalone

# Stop Docker services
docker-compose down

# Start standalone services
./start_server.sh

Standalone to Docker

# Stop standalone processes (Ctrl+C or kill PID)
# Then start Docker
./deploy.sh production

Both modes read the same inventory.env, so configuration is preserved.

---

Common Tasks

View Logs

Docker Mode:

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend

Standalone Mode:

# Backend
tail -f logs/backend.log

# Frontend
tail -f logs/frontend.log

Stop Services

Docker Mode:

docker-compose down

Standalone Mode:

# Press Ctrl+C in the terminal where start_server.sh is running
# Or find and kill the processes
ps aux | grep -E "uvicorn|node.*server"
kill <PID>

Change Ports

1. Edit inventory.env
2. Change BACKEND_PORT and/or FRONTEND_PORT
3. Redeploy:
   • Docker: ./deploy.sh production
   • Standalone: ./start_server.sh

Check Health Status

Docker Mode:

docker-compose ps
# All services should show "healthy" status

# Or call health endpoint
curl http://localhost:8000/health

Standalone Mode:

curl http://localhost:8000/health
curl http://localhost:3000/

---

Troubleshooting

Port Already in Use

Error: Port XXXX already in use

Solution:

1. Find what's using the port: lsof -i :XXXX or netstat -tuln | grep XXXX
2. Stop the application: kill <PID>
3. Or change the port in inventory.env

Health Check Timeout

Error: Services did not become healthy within timeout

Solution:

1. Check logs: docker-compose logs (Docker) or tail -f logs/*.log (Standalone)
2. Common causes:
   • Insufficient disk space
   • Database initialization slow on first run
   • Port still in use by old process
3. Retry: ./deploy.sh production (Docker) or restart (Standalone)

Database Locked

Error: database is locked

Solution:

# Docker: Restart backend
docker-compose restart backend

# Standalone: Kill and restart
kill <backend-pid>
./start_server.sh

HTTPS Certificate Warning

Issue: Browser shows certificate warning on first access

Explanation: Caddy generates self-signed certificates for local HTTPS. This is normal and secure.

Solution: Click "Advanced" and "Proceed Anyway" (Chrome) or similar button. The warning will not reappear once the certificate is accepted.

Can't Access Frontend/Backend

Error: Connection refused or timeout

Debugging:

# Check if service is running
docker-compose ps  # Docker
ps aux | grep -E "uvicorn|node"  # Standalone

# Check if port is listening
netstat -tuln | grep -E "8000|3000"

# Test direct connection
curl http://localhost:8000/health
curl http://localhost:3000/

---

Performance & Scaling

Single-Instance System

This deployment is optimized for single-instance operation:

• Database: SQLite (embedded)
• Storage: Local filesystem
• Capacity: ~5 concurrent users, ~10K items

Monitoring Performance

# Check process resource usage (Docker)
docker stats

# Check logs for slow queries
docker-compose logs backend | grep "duration"

Backup & Recovery

See docs/BACKUP_RUNBOOK.md for detailed backup procedures.

---

Production Deployment

Before Going Live

1. Change JWT_SECRET_KEY to a secure value
2. Update ALLOWED_ORIGINS to match your domain
3. Set LOG_LEVEL=WARNING to reduce log volume
4. Test the application thoroughly
5. Set up automated backups
6. Configure firewall to expose only required ports (3000, 8000, 443)
7. Review inventory.env for all sensitive values

Production Checklist

# Pre-deployment validation
bash .env.validation.sh

# Deploy
./deploy.sh production

# Verify all services
docker-compose ps
curl https://your-domain:8919/  # HTTPS frontend

# Monitor logs
docker-compose logs -f

Ongoing Maintenance

• Monitor logs daily
• Check health status weekly
• Perform backups daily/weekly per your retention policy
• Review resource usage monthly

---

Support & Logs

Enable Debug Logging

Edit inventory.env:

LOG_LEVEL=DEBUG

Then redeploy or restart services.

Collect Diagnostic Information

# Docker
docker-compose logs --tail=200 > diagnostics.log
docker-compose ps >> diagnostics.log
docker stats --no-stream >> diagnostics.log

# Standalone
tail -100 logs/*.log > diagnostics.log
ps aux | grep -E "uvicorn|node" >> diagnostics.log

---

Next Steps

• Backup Strategy: See docs/BACKUP_RUNBOOK.md
• API Documentation: http://localhost:8000/docs
• User Guide: See USER_GUIDE.md
• Architecture: See PROJECT_ARCHITECTURE.md

---

Last Updated: 2026-04-22
Version: Phase 6, Plan 1
Support: Check logs and troubleshooting section above