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
```bash
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
```bash
# 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
```bash
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
```bash
cd tfm-inventory
cp inventory.env.template inventory.env

# Edit configuration as needed
nano inventory.env
```

### Step 2: Install Dependencies
```bash
# Backend dependencies
cd backend
pip install -r requirements.txt
cd ..

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

### Step 3: Start Servers
```bash
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
```bash
# Stop Docker services
docker-compose down

# Start standalone services
./start_server.sh
```

### Standalone to Docker
```bash
# 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:**
```bash
# All services
docker-compose logs -f

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

**Standalone Mode:**
```bash
# Backend
tail -f logs/backend.log

# Frontend
tail -f logs/frontend.log
```

### Stop Services

**Docker Mode:**
```bash
docker-compose down
```

**Standalone Mode:**
```bash
# 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:**
```bash
docker-compose ps
# All services should show "healthy" status

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

**Standalone Mode:**
```bash
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**:
```bash
# 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**:
```bash
# 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
```bash
# 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
```bash
# 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`:
```bash
LOG_LEVEL=DEBUG
```

Then redeploy or restart services.

### Collect Diagnostic Information
```bash
# 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