solventum-image-metadata/PRODUCTION-DEPLOY.md

Production Deployment Guide

Quick guide for deploying Oliver Metadata Tool v4.0 to Ubuntu server.

📋 Prerequisites

1. Server Setup:

   • Ubuntu 20.04+ server
   • Docker & Docker Compose installed
   • Node.js 18+ & npm installed
   • Apache/Nginx configured as reverse proxy

2. Required Files:

   • .env file in project root with production values
   • Apache/Nginx config for reverse proxy

3. Repository Location:

   • Clone to: /opt/solventum-image-metadata/
   • Frontend serves from: /var/www/html/solventum-image-metadata/

🚀 Quick Deployment

First-Time Setup

# 1. Clone repository
cd /opt
sudo git clone <repository-url> solventum-image-metadata
cd solventum-image-metadata

# 2. Create .env file
sudo cp .env.production .env
sudo nano .env  # Edit with production values

# 3. Configure frontend volume in docker-compose
sudo nano docker-compose.fastapi.yml
# Comment out line 69: - ./frontend/dist:/app/frontend/dist:ro

# 4. Run deployment
sudo ./deploy.sh

Subsequent Updates

# Just run the deploy script - it handles everything!
cd /opt/solventum-image-metadata
sudo ./deploy.sh

The script automatically:

• ✅ Pulls latest code from git
• ✅ Cleans old Docker images
• ✅ Builds new containers
• ✅ Initializes database (first run only)
• ✅ Builds React frontend
• ✅ Deploys frontend to /var/www/html/
• ✅ Runs health checks

🧹 Clean Deployment (Remove Old Builds)

If you need to completely clean up before deploying:

cd /opt/solventum-image-metadata

# Option 1: Quick cleanup (recommended)
sudo docker-compose -f docker-compose.fastapi.yml down
sudo docker images | grep -E "oliver|solventum" | awk '{print $3}' | xargs -r sudo docker rmi -f
sudo docker system prune -f

# Option 2: Nuclear cleanup (see CLEANUP-COMMANDS.md)
# Use only if you want to delete everything including database

Then run sudo ./deploy.sh

⚙️ Configuration Files

.env File (Production)

Required environment variables:

# OpenAI (required for AI features)
OPENAI_API_KEY=sk-proj-...
AI_MODEL=gpt-5.2

# Azure AD SSO
AZURE_TENANT_ID=e519c2e6-bc6d-4fdf-8d9c-923c2f002385
AZURE_CLIENT_ID=9079054c-9620-4757-a256-23413042f1ef
AZURE_CLIENT_SECRET=your-secret-here
REDIRECT_URI=https://ai-sandbox.oliver.solutions/solventum-image-metadata/

# Security
SECRET_KEY=your-production-secret-key-here

# Backend
BACKEND_PORT=5001
DEBUG=false

Apache Virtual Host Example

<Location /solventum-image-metadata/api>
    ProxyPass http://localhost:5001
    ProxyPassReverse http://localhost:5001
</Location>

<Location /solventum-image-metadata/auth>
    ProxyPass http://localhost:5001/auth
    ProxyPassReverse http://localhost:5001/auth
</Location>

# Serve frontend static files
Alias /solventum-image-metadata /var/www/html/solventum-image-metadata
<Directory /var/www/html/solventum-image-metadata>
    Options -Indexes +FollowSymLinks
    AllowOverride None
    Require all granted

    # React Router support
    RewriteEngine On
    RewriteBase /solventum-image-metadata/
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /solventum-image-metadata/index.html [L]
</Directory>

🔍 Post-Deployment Verification

# 1. Check Docker containers
sudo docker ps | grep oliver

# 2. Check backend health
curl http://localhost:5001/health

# 3. Check API docs
curl http://localhost:5001/docs

# 4. Check frontend files
ls -lh /var/www/html/solventum-image-metadata/

# 5. View logs
cd /opt/solventum-image-metadata
sudo docker-compose -f docker-compose.fastapi.yml logs -f backend

🔧 Useful Commands

# View deployment logs
cd /opt/solventum-image-metadata
sudo docker-compose -f docker-compose.fastapi.yml logs -f

# Restart backend only
sudo docker-compose -f docker-compose.fastapi.yml restart backend

# Stop all services
sudo docker-compose -f docker-compose.fastapi.yml down

# Start services
sudo docker-compose -f docker-compose.fastapi.yml up -d

# Access Redis CLI
sudo docker exec -it oliver-redis redis-cli

# Check database
sudo ls -lh /opt/solventum-image-metadata/backend/data/

# Backup database
sudo cp backend/data/oliver_metadata.db backend/data/oliver_metadata.db.backup-$(date +%Y%m%d)

🚨 Troubleshooting

Deployment fails with "Git pull failed"

cd /opt/solventum-image-metadata
sudo git status
sudo git stash  # If uncommitted changes
sudo git pull origin main
sudo ./deploy.sh

Backend health check fails

# Check logs
sudo docker-compose -f docker-compose.fastapi.yml logs backend

# Common issues:
# 1. OPENAI_API_KEY not set
# 2. Redis not running
# 3. Port 5001 already in use

Frontend not loading

# Check files exist
ls -lh /var/www/html/solventum-image-metadata/

# Check permissions
sudo chown -R www-data:www-data /var/www/html/solventum-image-metadata/
sudo chmod -R 755 /var/www/html/solventum-image-metadata/

# Check Apache config
sudo apache2ctl -t
sudo systemctl reload apache2

"Docker build failed"

# Clean Docker completely
sudo docker system prune -af --volumes
sudo systemctl restart docker
sudo ./deploy.sh

📊 Monitoring

Check disk space

# Docker disk usage
sudo docker system df

# Project disk usage
du -sh /opt/solventum-image-metadata
du -sh /var/www/html/solventum-image-metadata

Check logs

# Backend logs (last 100 lines)
cd /opt/solventum-image-metadata
sudo docker-compose -f docker-compose.fastapi.yml logs --tail=100 backend

# Follow logs in real-time
sudo docker-compose -f docker-compose.fastapi.yml logs -f

🔒 Security Notes

1. Never commit .env files with secrets to git
2. Use strong SECRET_KEY in production
3. Backup database regularly before updates
4. Use HTTPS for production (configure in Apache/Nginx)
5. Review CORS settings in backend/app/main.py if needed

📞 Support

For issues:

1. Check logs: docker-compose logs
2. Review CLEANUP-COMMANDS.md for cleanup options
3. See DEPLOYMENT-CHECKLIST.md for detailed steps