solventum-image-metadata/DEPLOYMENT.md

Production Deployment Guide

Server: Ubuntu + Apache

Production deployment на https://ai-sandbox.oliver.solutions/solventum-image-metadata/

Prerequisites

1. Install System Dependencies

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt install docker-compose-plugin

# Install Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Verify versions
docker --version
docker compose version
node --version
npm --version

2. Configure Apache

# Enable required modules
sudo a2enmod proxy proxy_http headers rewrite ssl

# Copy Apache config
sudo cp /opt/solventum-image-metadata/apache-config.conf \
        /etc/apache2/sites-available/solventum-image-metadata.conf

# Enable site
sudo a2ensite solventum-image-metadata

# Test config
sudo apache2ctl configtest

# Reload Apache
sudo systemctl reload apache2

3. Setup SSL (Let's Encrypt)

# Install Certbot
sudo apt install certbot python3-certbot-apache

# Get certificate
sudo certbot --apache -d ai-sandbox.oliver.solutions

# Auto-renewal
sudo systemctl enable certbot.timer

Initial Deployment

1. Clone Repository

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

2. Configure Environment

# Copy environment template
sudo cp .env.fastapi.example .env

# Edit configuration
sudo nano .env

Required variables:

SECRET_KEY=<generate-with-python-secrets>
OPENAI_API_KEY=sk-...
AZURE_CLIENT_ID=9079054c-9620-4757-a256-23413042f1ef
AZURE_TENANT_ID=e519c2e6-bc6d-4fdf-8d9c-923c2f002385
AZURE_REDIRECT_URI=https://ai-sandbox.oliver.solutions/solventum-image-metadata/api/auth/microsoft/callback

Generate SECRET_KEY:

python3 -c "import secrets; print(secrets.token_hex(32))"

3. Create Required Directories

# Create data directories
sudo mkdir -p /opt/solventum-image-metadata/backend/{data,uploads,output/templates}
sudo mkdir -p /var/www/html/solventum-image-metadata

# Set permissions
sudo chown -R www-data:www-data /var/www/html/solventum-image-metadata
sudo chown -R $USER:$USER /opt/solventum-image-metadata/backend

4. Initial Deploy

cd /opt/solventum-image-metadata
sudo ./deploy.sh

Updates / Re-deployment

# 1. Pull latest code (as normal user with git access)
cd /opt/solventum-image-metadata
git pull origin main

# 2. Run deployment script (as root)
sudo ./deploy.sh

The script is idempotent - safe to run multiple times.

What the Deploy Script Does

1. ✅ Pre-flight checks (Docker, Node, permissions)
2. ✅ Validates environment variables
3. ✅ Builds Docker containers (with cache)
4. ✅ Stops old containers gracefully
5. ✅ Starts new containers (Redis + Backend)
6. ✅ Waits for Redis to be ready
7. ✅ Initializes database (first run only)
8. ✅ Installs frontend dependencies (npm ci)
9. ✅ Builds frontend (Vite production build)
10. ✅ Backs up existing frontend files
11. ✅ Deploys new frontend to /var/www/html/
12. ✅ Sets correct permissions (www-data)
13. ✅ Health checks (backend + Redis)
14. ✅ Cleanup old Docker images

Verification

1. Check Services

# Docker containers
docker ps

# Backend logs
docker logs oliver-backend

# Redis logs
docker logs oliver-redis

2. Test Endpoints

# Backend health
curl http://localhost:8000/health

# API docs
curl http://localhost:8000/docs

# Frontend (through Apache)
curl https://ai-sandbox.oliver.solutions/solventum-image-metadata/

3. Test Full Flow

1. Open https://ai-sandbox.oliver.solutions/solventum-image-metadata/
2. Click "Login with Microsoft" (should redirect to Azure AD)
3. After SSO, should redirect back to dashboard
4. Upload a test file
5. Edit metadata
6. Download file
7. Verify metadata: exiftool downloaded_file.pdf

Troubleshooting

Backend not starting

# Check backend logs
docker logs oliver-backend --tail 100

# Check if port 8000 is already in use
sudo lsof -i :8000

# Restart backend
docker restart oliver-backend

Redis connection error

# Check Redis
docker exec oliver-redis redis-cli ping
# Should return: PONG

# Check Redis logs
docker logs oliver-redis

# Restart Redis
docker restart oliver-redis

Frontend 404 errors

# Check Apache config
sudo apache2ctl configtest

# Check file permissions
ls -la /var/www/html/solventum-image-metadata/

# Should be owned by www-data
sudo chown -R www-data:www-data /var/www/html/solventum-image-metadata/

# Check Apache error log
sudo tail -f /var/log/apache2/solventum-image-metadata-error.log

API proxy errors

# Check if proxy modules enabled
apache2ctl -M | grep proxy

# Should see:
#  proxy_module (shared)
#  proxy_http_module (shared)

# Enable if missing
sudo a2enmod proxy proxy_http

# Restart Apache
sudo systemctl restart apache2

SSO redirect loop

# Verify REDIRECT_URI in .env matches Apache config
grep AZURE_REDIRECT_URI /opt/solventum-image-metadata/.env

# Should be:
# AZURE_REDIRECT_URI=https://ai-sandbox.oliver.solutions/solventum-image-metadata/api/auth/microsoft/callback

# Check Azure AD app registration
# Redirect URI must match exactly (including /api/ prefix)

Database locked

# Check if multiple backends running
docker ps | grep oliver-backend

# Stop all and restart
docker stop oliver-backend
docker start oliver-backend

Rollback

If deployment fails and you need to rollback:

# 1. Stop new containers
docker-compose -f docker-compose.fastapi.yml down

# 2. Restore frontend from backup
sudo rm -rf /var/www/html/solventum-image-metadata/*
sudo cp -r /tmp/oliver-metadata-backup-TIMESTAMP/* /var/www/html/solventum-image-metadata/

# 3. Start old Flask app (if available)
docker-compose -f docker-compose.yml up -d

# 4. Check logs
docker logs oliver-metadata-tool

Maintenance

Regular Tasks

Daily:

• Monitor disk space: df -h
• Check Docker logs: docker logs oliver-backend --tail 100

Weekly:

• Cleanup old uploads: Files older than 7 days auto-deleted
• Check Redis memory: docker exec oliver-redis redis-cli info memory

Monthly:

• Update system packages: sudo apt update && sudo apt upgrade
• Renew SSL certificate (auto with certbot)
• Review logs for errors

Backup Strategy

Database:

# Backup SQLite database
sudo cp /opt/solventum-image-metadata/backend/data/oliver_metadata.db \
       /opt/backups/oliver_metadata_$(date +%Y%m%d).db

# Automated daily backup (crontab)
0 2 * * * cp /opt/solventum-image-metadata/backend/data/oliver_metadata.db /opt/backups/oliver_metadata_$(date +\%Y\%m\%d).db

Uploads:

# Backup uploads directory
sudo tar -czf /opt/backups/uploads_$(date +%Y%m%d).tar.gz \
             /opt/solventum-image-metadata/backend/uploads/

Redis (if critical data):

# Redis snapshot (runs automatically with AOF enabled)
docker exec oliver-redis redis-cli BGSAVE

# Copy RDB file
docker cp oliver-redis:/data/dump.rdb /opt/backups/redis_$(date +%Y%m%d).rdb

Monitoring

Health Checks

# Backend
curl http://localhost:8000/health

# Redis
docker exec oliver-redis redis-cli ping

# Frontend
curl https://ai-sandbox.oliver.solutions/solventum-image-metadata/

Logs

# Backend logs
docker logs oliver-backend -f

# Redis logs
docker logs oliver-redis -f

# Apache logs
sudo tail -f /var/log/apache2/solventum-image-metadata-access.log
sudo tail -f /var/log/apache2/solventum-image-metadata-error.log

Performance

# Docker stats
docker stats oliver-backend oliver-redis

# Disk usage
du -sh /opt/solventum-image-metadata/backend/uploads/

# Redis memory
docker exec oliver-redis redis-cli info memory | grep used_memory_human

Security Checklist

• SSL enabled (HTTPS)
• SECRET_KEY is random (not default)
• OPENAI_API_KEY secured in .env
• Azure AD credentials secured
• File permissions set to www-data
• Database not publicly accessible
• Redis not exposed externally
• CORS restricted to frontend domain
• Apache security headers enabled
• Regular backups configured

Support

• API Documentation: http://localhost:8000/docs
• Deployment Script: /opt/solventum-image-metadata/deploy.sh
• Logs Directory: /var/log/apache2/
• Application Logs: docker logs oliver-backend

---

Last updated: 2026-02-09