tfm_ainventory/docs/CONFIGURATION_REFERENCE.md

# Configuration Reference

**Purpose**: Document all configuration parameters for both Docker and Standalone deployment modes.  
**Shared Config**: inventory.env (used by both modes)  
**Last Updated**: 2026-04-22

---

## Overview

Both Docker and Standalone deployment modes use the same `inventory.env` configuration file. All parameters are documented here with defaults, ranges, and examples.

---

## inventory.env Parameters

### Network & Server Configuration

```bash
# Backend API server port (Docker exposed on this port)
BACKEND_PORT=8000
# Default: 8000
# Range: 1024-65535
# Common: 8000, 8080, 5000

# Frontend server port
FRONTEND_PORT=3000
# Default: 3000
# Range: 1024-65535
# Common: 3000, 3001, 8888

# Host binding (0.0.0.0 = all interfaces, 127.0.0.1 = localhost only)
BACKEND_HOST=0.0.0.0
FRONTEND_HOST=0.0.0.0
# Use 127.0.0.1 for development only, 0.0.0.0 for production

# External server address (for CORS and frontend API calls)
SERVER_URL=http://localhost:8000
# Example for production: http://inventory.example.com:8000
# Or with HTTPS: https://inventory.example.com
```

### Security & Authentication

```bash
# JWT secret key for API authentication (generate with: openssl rand -hex 32)
JWT_SECRET_KEY=your-generated-hex-string-here
# Min length: 32 characters
# IMPORTANT: Change this in production
# Generation: openssl rand -hex 32

# Algorithm for JWT signing
JWT_ALGORITHM=HS256
# Default: HS256
# Options: HS256, HS384, HS512

# LDAP server configuration (optional, for enterprise auth)
LDAP_SERVER=ldap.example.com
LDAP_PORT=389
LDAP_BIND_DN=cn=admin,dc=example,dc=com
LDAP_BASE_DN=ou=users,dc=example,dc=com
LDAP_USE_SSL=false
# Set to empty/false to disable LDAP (use local auth only)

# Password hashing iterations (PBKDF2)
PASSWORD_HASH_ITERATIONS=100000
# Default: 100000
# Higher = more secure but slower
```

### Database Configuration

```bash
# Database file location
DATABASE_URL=sqlite:///./data/inventory.db
# For Docker: Use /app/data/inventory.db inside container
# For Standalone: Use ./data/inventory.db

# Database connection pool size
DB_POOL_SIZE=10
# Default: 10
# Increase for 10+ concurrent users
# Docker: Keep <20 due to SQLite single-writer
# Standalone: Keep <15

# Database WAL mode (write-ahead logging, improves concurrency)
DATABASE_JOURNAL_MODE=WAL
# Default: WAL
# Options: WAL, DELETE
# WAL = better concurrency, more disk space
# DELETE = less disk, slower writes
```

### AI Provider Configuration

```bash
# Primary AI provider (gemini or claude)
PRIMARY_AI_PROVIDER=gemini
# Options: gemini, claude
# Default: gemini (more cost-effective)

# Google Gemini API key (for label extraction)
GEMINI_API_KEY=your-api-key-here
# Get from: https://aistudio.google.com/app/apikeys
# Leave empty to disable Gemini

# Anthropic Claude API key (for label extraction)
CLAUDE_API_KEY=your-api-key-here
# Get from: https://console.anthropic.com/
# Leave empty to disable Claude

# AI model selection
GEMINI_MODEL=gemini-2.0-flash
CLAUDE_MODEL=claude-3-5-sonnet-20241022
# Use latest stable versions available

# AI image processing mode (box or standard)
AI_BOX_DISCOVERY_MODE=false
# Set to true for enhanced box label detection
# Default: false (standard detection)

# AI request timeout (seconds)
AI_REQUEST_TIMEOUT=30
# Default: 30 seconds
# Increase for slower connections
```

### Logging Configuration

```bash
# Log level for backend
LOG_LEVEL=INFO
# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
# DEBUG = verbose (development)
# INFO = normal (production)
# ERROR = minimal output

# Log file location
LOG_FILE=./logs/backend.log
# For Docker: /app/logs/backend.log
# For Standalone: ./logs/backend.log

# Maximum log file size before rotation
LOG_MAX_SIZE=10485760  # 10MB
# Default: 10MB

# Number of backup log files to keep
LOG_BACKUP_COUNT=5
# Default: 5 files
```

### CORS & Network Security

```bash
# Allowed origins for CORS (comma-separated)
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8906
# Add additional IPs/domains here
# Example for production:
# ALLOWED_ORIGINS=https://inventory.example.com,https://app.example.com

# Extra allowed origins (for VPN/Tailscale IPs)
EXTRA_ALLOWED_ORIGINS=10.0.0.0/8
# Supports IP addresses, CIDR ranges, domain names
# Comma-separated for multiple entries

# Enable CORS credentials (cookies, auth headers)
CORS_CREDENTIALS=true
# Default: true
```

### Feature Flags

```bash
# Enable AI-powered label extraction
ENABLE_AI_EXTRACTION=true
# Default: true
# Set to false if no API keys configured

# Enable offline sync
ENABLE_OFFLINE_SYNC=true
# Default: true
# Keep enabled for field operations

# Enable QR code scanning
ENABLE_QR_SCANNING=true
# Default: true
# Core feature, always enabled

# Enable box labeling system
ENABLE_BOX_LABELS=true
# Default: true
# v1.5.0+ feature
```

### Performance & Optimization

```bash
# API request timeout (seconds)
REQUEST_TIMEOUT=30
# Default: 30 seconds
# Increase if experiencing slow connections

# Database query timeout (seconds)
DATABASE_TIMEOUT=10
# Default: 10 seconds
# Increase for large datasets (10K+ items)

# Backend worker threads
WORKERS=4
# For Standalone mode (if using Gunicorn)
# Default: 4
# Increase for high concurrency
# Formula: (2 x CPUs) + 1

# Frontend build optimization
NEXT_PUBLIC_OPTIMIZE_IMAGES=true
# Default: true
# Enable for production deployments
```

### Deployment & Version

```bash
# Application version (auto-managed)
VERSION=1.14.6
# Updated by: scripts/save_version.py
# Do not edit manually

# Environment (development, staging, production)
ENVIRONMENT=production
# Options: development, staging, production
# Affects logging, error messages, CORS strictness

# Docker image tag (if using docker-compose)
DOCKER_IMAGE_TAG=latest
# Options: latest, stable, v1.14.6, custom-tag
```

### Backup & Operations

```bash
# Backup directory (relative path)
BACKUP_DIR=./backups
# Default: ./backups
# For Docker: /app/backups (persisted volume)

# Backup retention (days)
BACKUP_RETENTION_DAILY=30
BACKUP_RETENTION_WEEKLY=90
# Default: 30 days (daily), 90 days (weekly)

# Enable automated backups (cron)
ENABLE_CRON_BACKUPS=true
# Default: true
# Requires: sudo bash config/backup-cron.sh
```

---

## Docker-Specific Configuration

### docker-compose.yml

These are handled by the deployment but documented for reference:

```yaml
# Backend service
backend:
  environment:
    - DATABASE_URL=sqlite:////app/data/inventory.db
    - LOG_FILE=/app/logs/backend.log
    - PYTHONUNBUFFERED=1
  ports:
    - "${BACKEND_PORT}:8000"
  volumes:
    - ./data:/app/data
    - ./config:/app/config
    - ./logs:/app/logs

# Frontend service
frontend:
  environment:
    - NEXT_PUBLIC_API_URL=http://localhost:${BACKEND_PORT}
  ports:
    - "${FRONTEND_PORT}:3000"

# Proxy service (Caddy)
proxy:
  ports:
    - "8909:8909"  # HTTPS proxy
  volumes:
    - ./data/caddy_data:/data
    - ./data/caddy_config:/config
```

---

## Standalone-Specific Configuration

### Environment Variables for start_server.sh

The script reads from `inventory.env` and sets up:

```bash
# Python environment
PYTHONUNBUFFERED=1  # Direct logging output
PYTHONPATH=./backend

# Node environment
NODE_ENV=production

# Paths
BACKEND_DIR=./backend
FRONTEND_DIR=./frontend
DATA_DIR=./data
LOGS_DIR=./logs
```

---

## Configuration Validation

### Pre-Deployment Checks

Run these to validate configuration before starting services:

```bash
# Docker mode
./deploy.sh validate

# Standalone mode
python3 backend/config_manager.py --validate

# Manual checks
[ -f inventory.env ] && echo "✓ inventory.env exists"
[ -d data ] && echo "✓ data directory exists"
[ -d logs ] && echo "✓ logs directory exists"
openssl rand -hex 32 > /dev/null && echo "✓ OpenSSL available"
```

---

## Common Configuration Scenarios

### Scenario 1: Local Development

```bash
BACKEND_PORT=8000
FRONTEND_PORT=3000
BACKEND_HOST=127.0.0.1
JWT_SECRET_KEY=dev-key-not-for-production
LOG_LEVEL=DEBUG
ENVIRONMENT=development
ENABLE_AI_EXTRACTION=false  # Save API costs
```

### Scenario 2: Single-Server Production

```bash
BACKEND_PORT=8000
FRONTEND_PORT=3000
BACKEND_HOST=0.0.0.0
SERVER_URL=https://inventory.example.com
JWT_SECRET_KEY=<generate-with-openssl>
LOG_LEVEL=INFO
ENVIRONMENT=production
PRIMARY_AI_PROVIDER=gemini
GEMINI_API_KEY=<your-api-key>
```

### Scenario 3: High Concurrency (Standalone)

```bash
DB_POOL_SIZE=15
WORKERS=8  # (2 x CPUs) + 1
REQUEST_TIMEOUT=45
DATABASE_TIMEOUT=15
LOG_LEVEL=WARNING  # Reduce I/O for performance
```

### Scenario 4: LDAP Enterprise Auth

```bash
LDAP_SERVER=ldap.company.com
LDAP_PORT=389
LDAP_BIND_DN=cn=admin,dc=company,dc=com
LDAP_BASE_DN=ou=people,dc=company,dc=com
LDAP_USE_SSL=true
# Users login with their LDAP credentials
```

---

## Troubleshooting Configuration Issues

### Port Already in Use

```bash
# Find process using port
lsof -i :8000
netstat -tuln | grep 8000

# Solution: Change BACKEND_PORT or kill process
```

### JWT Secret Not Set

```bash
# Generate new secret
openssl rand -hex 32

# Add to inventory.env
echo "JWT_SECRET_KEY=$(openssl rand -hex 32)" >> inventory.env
```

### Database Connection Error

```bash
# Check database file exists
ls -la data/inventory.db

# Check permissions
chmod 644 data/inventory.db

# Reset if corrupted
rm data/inventory.db
# (Backup will be restored on next startup)
```

### LDAP Authentication Failing

```bash
# Test LDAP connection
ldapsearch -x -H ldap://ldap.company.com:389 -D "cn=admin,dc=company,dc=com"

# Check configuration matches LDAP schema
# May need to adjust LDAP_BASE_DN or LDAP_BIND_DN
```

---

## Environment Variable Precedence

Configuration is loaded in this order:

1. Defaults (hardcoded in code)
2. `inventory.env` file
3. OS environment variables (override)
4. Command-line arguments (highest priority)

Example override:
```bash
BACKEND_PORT=9000 ./deploy.sh production
```

---

## Security Best Practices

- [ ] Generate unique JWT_SECRET_KEY for each environment
- [ ] Never commit `inventory.env` to git (add to `.gitignore`)
- [ ] Use HTTPS in production (configure reverse proxy)
- [ ] Rotate LDAP passwords quarterly
- [ ] Limit ALLOWED_ORIGINS to known domains
- [ ] Use strong JWT_ALGORITHM (HS256 minimum)
- [ ] Monitor LOG_LEVEL in production (avoid DEBUG)

---

**Version**: 1.0  
**Last Updated**: 2026-04-22  
**Maintained By**: Operations Team