tfm_ainventory/STANDALONE_DEPLOYMENT.md

Standalone Deployment Guide

This document covers deploying TFM aInventory v2.0 without Docker using the start_servers.py script.

Quick Start

# From project root:
python3 start_servers.py

The script will:

1. ✓ Validate configuration (inventory.env)
2. ✓ Create Python virtual environment if needed
3. ✓ Install backend dependencies
4. ✓ Install and build frontend
5. ✓ Start backend (FastAPI on port 8916)
6. ✓ Start frontend (Next.js on port 8917)
7. ✓ Monitor both services

Requirements

• Python 3.10+ with venv module
• Node.js 18+ with npm
• Linux/macOS (Windows requires WSL2)
• Ports 8916 (backend) and 8917 (frontend) available

Configuration

Edit inventory.env to customize:

BACKEND_PORT=8916          # FastAPI backend port
FRONTEND_PORT=8917         # Next.js frontend port
DATA_DIR=./data            # Persistent data location
LOGS_DIR=./logs            # Application logs
LOG_LEVEL=INFO             # Log verbosity (INFO, DEBUG, WARNING, ERROR)

Accessing the Application

• Frontend: http://localhost:8917
• Backend API: http://localhost:8916
• API Docs: http://localhost:8916/docs (Swagger UI)

Logs

Application logs are written to:

• Backend: ./logs/backend.log
• Frontend: ./logs/frontend.log

Monitor in real-time:

tail -f logs/backend.log
tail -f logs/frontend.log

Stopping Servers

Press Ctrl+C in the terminal running start_servers.py.

The script will gracefully terminate both services.

Troubleshooting

Port Already in Use

If port 8916 or 8917 is already in use:

# Find process using the port:
lsof -i :8916
lsof -i :8917

# Kill the process:
kill -9 <PID>

# Or change the port in inventory.env and restart

Virtual Environment Issues

If you get "externally-managed-environment" error:

# Remove the venv and let the script recreate it:
rm -rf .venv
python3 start_servers.py

Frontend Build Failures

If Next.js build fails:

# Clean and rebuild:
rm -rf frontend/.next frontend/node_modules
python3 start_servers.py

Backend Won't Start

Check backend logs:

tail -50 logs/backend.log

Common issues:

• Database initialization error: Check ./data/ directory permissions
• Missing dependencies: Delete .venv and restart
• Module import errors: Check backend/requirements.txt is complete

Comparison with Docker Deployment

Aspect	Standalone	Docker
Startup time	20-30s	2-3 min
Isolation	None	Full containers
Development	Faster iteration	Consistent environment
Production	Not recommended	Recommended
Troubleshooting	Easier (shared logs)	Requires docker logs

Production Deployment

For production deployments, use ./deploy.sh which orchestrates Docker Compose:

./deploy.sh

See DEPLOYMENT_QUICKSTART.md for details.

---

Last Updated: 2026-04-22
Python Version: 3.10+
Node Version: 18+