Upgrading¶

Safely upgrade the Employer File Validator to newer versions.

Before Upgrading¶

1. Backup Current State¶

# Export current .env
cp .env .env.backup

# Export volumes (if needed)
docker-compose exec backend tar czf /tmp/storage.tar.gz /app/storage
docker cp validation-backend:/tmp/storage.tar.gz ./backup-storage.tar.gz

# Note current version
curl http://localhost:8000/health | jq .version

2. Review Release Notes¶

Check for: - Breaking changes - New environment variables - Migration steps - Deprecations

3. Test in Staging¶

Always test upgrades in staging before production.

Upgrade Methods¶

Method 1: Pull New Images (Production)¶

For deployments using pre-built images:

# Stop services
docker-compose -f docker-compose.prod.yml down

# Pull latest images
docker-compose -f docker-compose.prod.yml pull

# Start with new images
docker-compose -f docker-compose.prod.yml up -d

# Check health
curl https://api.your-domain.com/health

Method 2: Specific Version¶

Deploy a specific version:

# Edit docker-compose.prod.yml
# Change image tag:
image: ghcr.io/praxisiq/newhires-backend:sha-abc1234

# Pull and restart
docker-compose -f docker-compose.prod.yml pull
docker-compose -f docker-compose.prod.yml up -d

Post-Upgrade Steps¶

1. Verify Services¶

# Check all services running
docker-compose ps

# Both should show: Up (healthy)

2. Test Core Functions¶

Upload test file
Validate file
Apply corrections
Download corrected file

3. Check LLM Integration¶

curl http://localhost:8000/health | jq .llm_enabled
# Should return: true

4. Review Logs¶

docker-compose logs --tail=100 backend
docker-compose logs --tail=100 frontend

# Look for errors or warnings

Rollback Procedure¶

If upgrade fails:

Quick Rollback (Images)¶

# Stop new version
docker-compose down

# Use previous image tag
# Edit docker-compose.prod.yml or docker-compose.yml
image: ghcr.io/praxisiq/newhires-backend:sha-previous

# Start old version
docker-compose up -d

Restore Backup¶

# Restore .env
cp .env.backup .env

# Restore volumes (if needed)
docker cp backup-storage.tar.gz validation-backend:/tmp/
docker-compose exec backend tar xzf /tmp/storage.tar.gz -C /

# Restart
docker-compose restart

Zero-Downtime Upgrade¶

For production with minimal downtime:

Using Blue-Green Deployment¶

Start new version on different ports
Test new version thoroughly
Update reverse proxy to point to new version
Monitor for issues
Stop old version after confirming success

Using Rolling Update¶

# Pull new images
docker-compose pull

# Update backend first
docker-compose up -d --no-deps backend

# Wait and verify
sleep 30
curl http://localhost:8000/health

# Then update frontend
docker-compose up -d --no-deps frontend

Environment Variable Changes¶

Check for New Variables¶

Review the Environment Configuration Example documentation for any new variables added in the latest version.

Compare your current .env with the latest template to identify new variables.

Add New Variables¶

# Add to .env
NEW_VARIABLE=value

# Restart services
docker-compose restart

Database Migrations¶

Currently, the system uses in-memory storage (no database). Future versions may include:

PostgreSQL for persistent storage
Migration scripts for schema changes
Data migration utilities

Version Compatibility¶

Semantic Versioning¶

System follows semantic versioning:

Major (1.x.x): Breaking changes
Minor (x.1.x): New features, backward compatible
Patch (x.x.1): Bug fixes

Compatibility Matrix¶

Version	Min Docker	Min Docker Compose	Python
1.x.x	20.10+	2.0+	3.9+

Monitoring Upgrades¶

Set Up Alerts¶

Monitor for: - Service health after upgrade - Error rate increases - Performance degradation - LLM integration issues

Automated Health Checks¶

#!/bin/bash
# post-upgrade-check.sh

echo "Checking backend health..."
if curl -f http://localhost:8000/health > /dev/null 2>&1; then
    echo "✅ Backend healthy"
else
    echo "❌ Backend unhealthy - rollback recommended"
    exit 1
fi

echo "Checking LLM integration..."
LLM_ENABLED=$(curl -s http://localhost:8000/health | jq -r .llm_enabled)
if [ "$LLM_ENABLED" = "true" ]; then
    echo "✅ LLM enabled"
else
    echo "⚠️ LLM disabled - check API key"
fi

echo "All checks passed"

Best Practices¶

✅ Always backup before upgrading
✅ Test in staging first
✅ Review release notes thoroughly
✅ Upgrade during low-traffic periods
✅ Have rollback plan ready
✅ Monitor closely after upgrade
✅ Keep at least one previous version available
✅ Document upgrade process and issues

Upgrade Checklist¶

- [ ] Review release notes from vendor
- [ ] Backup .env file
- [ ] Backup data/volumes
- [ ] Test in staging environment
- [ ] Schedule maintenance window
- [ ] Notify users (if applicable)
- [ ] Pull new Docker images
- [ ] Update .env with new variables (check docs)
- [ ] Start new version
- [ ] Verify health endpoints
- [ ] Test core functionality
- [ ] Monitor logs for errors
- [ ] Document any issues