Cortex-vLLM Configuration Checklist¶

✅ Pre-Start Checklist for Administrators¶

Before running make quick-start, verify these prerequisites:

System Requirements¶

Docker installed (v20.10+) - docker --version
Docker Compose installed (v2.0+) - docker compose version
Make utility installed - make --version
Bash shell available - bash --version
At least 8GB RAM available - free -h
At least 20GB disk space - df -h
User has Docker permissions - docker ps (should work without sudo)

Network Requirements¶

Host machine has a network interface (not just loopback)
Network interface has an IP address (check: ip addr show)
Ports 3001 and 8084 are not already in use - netstat -tuln | grep -E '3001|8084'

Optional (for GPU features)¶

NVIDIA GPU installed - nvidia-smi
NVIDIA drivers installed (v470+)
NVIDIA Container Toolkit installed

🚀 Installation Checklist¶

Step 1: Clone Repository¶

git clone <your-repo-url>
cd Cortex-vLLM

- [ ] Repository cloned successfully - [ ] In the Cortex-vLLM directory

Step 2: Verify IP Detection¶

bash scripts/detect-ip.sh

- [ ] Returns a valid IP address (not "localhost") - [ ] IP is your LAN IP (192.168.x.x or 10.x.x.x) - [ ] IP is NOT a Docker bridge (172.17-31.x.x)

If detection fails:

# Override manually
export HOST_IP=192.168.1.181  # Use your actual IP

Step 3: Start Cortex¶

make quick-start

- [ ] No errors during build - [ ] All containers start successfully - [ ] Output shows detected IP (verify it's correct) - [ ] Admin user created (admin/admin) - [ ] URLs are displayed

Step 4: Validate Configuration¶

make validate

- [ ] All tests pass (0 failed) - [ ] IP detected correctly - [ ] CORS includes your IP - [ ] Services are healthy - [ ] Network bindings correct

✅ Post-Start Verification Checklist¶

Gateway (Backend)¶

curl http://YOUR_IP:8084/health

- [ ] Returns: {"status":"ok"} - [ ] HTTP 200 status code - [ ] No connection errors

Frontend (Admin UI)¶

Can access: http://YOUR_IP:3001 in browser
Login page loads correctly
No CORS errors in browser console (F12)
Can login with admin/admin

Database¶

make db-shell
# Type: \dt
# Type: \q

- [ ] PostgreSQL shell opens - [ ] Tables exist (users, api_keys, organizations, etc.) - [ ] Can exit successfully

CORS Configuration¶

docker exec cortex-gateway-1 printenv CORS_ALLOW_ORIGINS

- [ ] Output includes your detected IP - [ ] Format is: http://YOUR_IP:3001,http://localhost:3001,http://127.0.0.1:3001 - [ ] No syntax errors

🌐 Network Access Checklist¶

From Host Machine¶

Can access frontend: http://YOUR_IP:3001
Can access gateway: http://YOUR_IP:8084
Can login to Admin UI
No CORS errors in browser console

From Another Device (Optional Test)¶

Firewall Configuration¶

# If using ufw (Ubuntu/Debian)
sudo ufw status

- [ ] Firewall allows port 3001 - [ ] Firewall allows port 8084 - [ ] Or firewall is disabled

If firewall is active, allow ports:

sudo ufw allow 3001/tcp
sudo ufw allow 8084/tcp

🔒 Security Checklist (Production)¶

Before Production Deployment¶

make prod-check

Required Changes: - [ ] Changed default admin password - [ ] Set GATEWAY_DEV_ALLOW_ALL_KEYS=false in docker.compose.prod.yaml - [ ] Set strong INTERNAL_VLLM_API_KEY - [ ] Reviewed CORS settings (restrict if needed) - [ ] TLS/SSL configured (nginx/traefik reverse proxy) - [ ] Automated backups configured (cron job) - [ ] Firewall rules configured - [ ] Regular monitoring set up

📊 Operational Checklist (Daily/Weekly)¶

Daily Checks¶

make status - All services running?
make health - All services healthy?
Check logs for errors: make logs-gateway | grep ERROR

Weekly Checks¶

make db-backup - Backup database
Review disk space: df -h
Review logs for patterns
Check for Docker updates

Monthly Checks¶

make prune - Clean unused Docker resources
Review security: make prod-check
Update containers if new versions available
Verify backups are restorable

🐛 Troubleshooting Checklist¶

If Services Won't Start¶

Run: make clean
Run: make install-deps
Run: make quick-start
Check: make logs for errors

If Can't Access UI¶

If CORS Errors¶

Check detection: make ip
Check CORS: docker exec cortex-gateway-1 printenv CORS_ALLOW_ORIGINS
Restart: make restart
Validate: make validate

If IP Detection Wrong¶

Test script: bash scripts/detect-ip.sh
Check interfaces: ip addr show
Override: export HOST_IP=YOUR_IP
Restart: make restart

📝 Configuration Files Checklist¶

DO NOT Edit These (Auto-Configured):¶

❌ Don't edit backend/src/config.py for CORS
❌ Don't hardcode IPs in any files
❌ Don't create .env files for IP configuration

MAY Edit These (If Needed):¶

✅ docker.compose.dev.yaml - For ports, paths, profiles
✅ docker.compose.prod.yaml - For production settings
✅ scripts/detect-ip.sh - Only if detection fails

Example Override in docker.compose.dev.yaml:¶

# ONLY if you need to change default paths or ports
environment:
  CORTEX_MODELS_DIR_HOST: /custom/path/to/models  # Custom model storage
  HF_CACHE_DIR_HOST: /custom/path/to/cache       # Custom HF cache

ports:
  - "8085:8084"  # If port 8084 conflicts

✨ Quick Validation (Run After Setup)¶

One command to validate everything:

make validate

Expected output:

Tests Passed:  10
Warnings:      0
Tests Failed:  0

✓ All checks passed! Cortex is properly configured.

Access Cortex at:
  Admin UI: http://192.168.1.181:3001
  Gateway:  http://192.168.1.181:8084

🎯 Success Criteria¶

✅ Cortex is Properly Configured When:¶

📞 Getting Help¶

If any checklist item fails:

Run diagnostics:

make validate > diagnostics.txt
make logs > logs.txt 2>&1
make ip

Review logs for errors:
```
make logs-gateway | grep -i error
```
Try clean restart:
```
make clean-all
make quick-start
```
Check documentation:
docs/getting-started/admin-setup.md - Setup walkthrough
docs/architecture/configuration-flow.md - How config works
docs/architecture/ip-detection.md - IP detection details
Quick fixes:
Wrong IP detected? → export HOST_IP=192.168.1.181 && make restart
CORS errors? → make restart
Services down? → make up
Database issues? → make db-reset (⚠️ deletes data!)

🎓 Understanding the Checks¶

What Each Validation Checks:¶

IP Detection → Ensures system can find your LAN IP
Container Status → Verifies all services are running
CORS Configuration → Confirms network access is allowed
Health Endpoints → Tests services respond correctly
Network Binding → Verifies services accept network connections
Firewall → Checks if ports are blocked

Why These Matter:¶

IP Detection → Without correct IP, network access fails
CORS → Without CORS, browser blocks API calls
Health → Unhealthy services can't process requests
Network Binding → Without 0.0.0.0 binding, only localhost works
Firewall → Blocked ports prevent network access

🎉 Completion Checklist¶

✅ Ready for Use When:¶

✅ Ready for Production When:¶

Quick Start: make quick-start then make validate 🚀