Daniel Bedeleanu
5f9c6aee5a
- Quick start instructions for start_servers.py - Configuration options and port mapping - Troubleshooting guide for common issues - Comparison with Docker deployment
138 lines
3.0 KiB
Markdown
138 lines
3.0 KiB
Markdown
# 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+
|