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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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

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

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)

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

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

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

# Solution: Change BACKEND_PORT or kill process

JWT Secret Not Set

# Generate new secret
openssl rand -hex 32

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

Database Connection Error

# 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

# 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:

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