From 5f9c6aee5a2998da1ef4cd207d1cf899e70ad62e Mon Sep 17 00:00:00 2001
From: Daniel Bedeleanu <bede@tfm.ro>
Date: Wed, 22 Apr 2026 18:42:06 +0300
Subject: [PATCH] docs: add standalone deployment guide

- Quick start instructions for start_servers.py
- Configuration options and port mapping
- Troubleshooting guide for common issues
- Comparison with Docker deployment
---
 STANDALONE_DEPLOYMENT.md | 137 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 STANDALONE_DEPLOYMENT.md

diff --git a/STANDALONE_DEPLOYMENT.md b/STANDALONE_DEPLOYMENT.md
new file mode 100644
index 00000000..a313f657
--- /dev/null
+++ b/STANDALONE_DEPLOYMENT.md
@@ -0,0 +1,137 @@
+# Standalone Deployment Guide
+
+This document covers deploying TFM aInventory v2.0 without Docker using the `start_servers.py` script.
+
+## Quick Start
+
+```bash
+# 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:
+
+```env
+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:
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+# Remove the venv and let the script recreate it:
+rm -rf .venv
+python3 start_servers.py
+```
+
+### Frontend Build Failures
+
+If Next.js build fails:
+
+```bash
+# Clean and rebuild:
+rm -rf frontend/.next frontend/node_modules
+python3 start_servers.py
+```
+
+### Backend Won't Start
+
+Check backend logs:
+```bash
+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:
+
+```bash
+./deploy.sh
+```
+
+See [DEPLOYMENT_QUICKSTART.md](docs/DEPLOYMENT_QUICKSTART.md) for details.
+
+---
+
+**Last Updated**: 2026-04-22  
+**Python Version**: 3.10+  
+**Node Version**: 18+