feat(6): phase 6 plan 02 - operational runbook and documentation
- Created OPERATIONAL_RUNBOOK.md: comprehensive step-by-step procedures for both Docker and Standalone deployment modes covering deployment, daily ops, troubleshooting, backup/restore, disaster recovery, scaling, and updates - Created HEALTH_MONITORING_CHECKLIST.md: daily/weekly/monthly health check procedures with alert thresholds and quick troubleshooting reference - Created DISASTER_RECOVERY_PLAN.md: detailed procedures for 6 failure scenarios (database corruption, hardware failure, data center failure, app crash, disk full, network isolation) with RTO/RPO targets - Created CONFIGURATION_REFERENCE.md: complete documentation of all inventory.env parameters for both deployment modes with common scenarios and troubleshooting - Created EMERGENCY_PROCEDURES.md: quick-reference incident response playbook with 7 critical scenarios, decision tree, escalation path, and printable cheat sheet - Created scripts/backup.sh: automated backup script supporting both Docker and Standalone with integrity verification and retention management - Created scripts/restore.sh: restore script with triple confirmation, safety backups, and validation tests for both deployment modes - Created config/backup-cron.sh: installer for daily/weekly automated backup cron jobs (2 AM daily, 3 AM Sunday) All documentation covers dual-deployment modes with shared configuration files. Documentation is operator-ready with copy-paste commands and clear expected outputs.
This commit is contained in:
382
docs/DEPLOYMENT_QUICKSTART.md
Normal file
382
docs/DEPLOYMENT_QUICKSTART.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user