hm_ems_report/DEPLOY.md

Deployment Guide - H&M EMS Product Review Tool

This guide covers deploying the H&M EMS application to an Ubuntu server with Apache.

Prerequisites

• Ubuntu server with Apache installed
• Python 3.8+
• Apache modules: proxy, proxy_http
• sudo access

Server Architecture

User Request (HTTPS)
    ↓
Apache (:443) - ai-sandbox.oliver.solutions
    ├─→ /hm-ems-report/ (static files) → /var/www/html/hm-ems-report/
    ├─→ /hm-ems-report/api/* (proxy) → Gunicorn :5000 → Flask
    └─→ /hm-ems-report/images/* → /opt/hm-ems-data/campaign_images/

Initial Setup

1. Clone Repository

sudo mkdir -p /opt
cd /opt
sudo git clone git@bitbucket.org:zlalani/hm_ems_report.git hm_ems_report
cd hm_ems_report

2. Create Data Directories

sudo mkdir -p /opt/hm-ems-data/Master_Json
sudo mkdir -p /opt/hm-ems-data/campaign_images
sudo mkdir -p /opt/hm-ems-data/backups
sudo mkdir -p /var/www/html/hm-ems-report
sudo mkdir -p /var/log/hm-ems

sudo chown -R vadym.samoilenko:vadym.samoilenko /opt/hm-ems-data
sudo chown -R vadym.samoilenko:vadym.samoilenko /var/www/html/hm-ems-report
sudo chown -R vadym.samoilenko:vadym.samoilenko /var/log/hm-ems

3. Upload Campaign Data

Upload your campaign JSON files and images:

# Example: Copy JSON files
sudo cp *.json /opt/hm-ems-data/Master_Json/
sudo chown vadym.samoilenko:vadym.samoilenko /opt/hm-ems-data/Master_Json/*.json

# Example: Copy campaign images
sudo cp -r campaign_images/* /opt/hm-ems-data/campaign_images/
sudo chown -R vadym.samoilenko:vadym.samoilenko /opt/hm-ems-data/campaign_images/

Expected structure:

/opt/hm-ems-data/
├── Master_Json/
│   ├── 1022A.json
│   └── 2023.json
└── campaign_images/
    ├── 2025/1022A/Automation_LR/*.jpg
    └── 2026/2023/Automation_LR/*.jpg

4. Configure Apache

Enable required modules:

sudo a2enmod proxy
sudo a2enmod proxy_http

Add to your Apache virtual host configuration (e.g., /etc/apache2/sites-available/000-default.conf):

# H&M EMS Review Tool
ProxyPass /hm-ems-report/api http://localhost:5000/api
ProxyPassReverse /hm-ems-report/api http://localhost:5000/api

Alias /hm-ems /var/www/html/hm-ems-report
<Directory /var/www/html/hm-ems-report>
    Options -Indexes +FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

Alias /hm-ems-report/images /opt/hm-ems-data/campaign_images
<Directory /opt/hm-ems-data/campaign_images>
    Options -Indexes +FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

Test and restart Apache:

sudo apachectl configtest
sudo systemctl restart apache2

5. Run Deployment Script

cd /opt/hm_ems_report
sudo ./deploy.sh

The script will:

• ✅ Create necessary directories
• ✅ Backup existing data
• ✅ Pull latest code from git
• ✅ Setup Python virtual environment
• ✅ Install dependencies
• ✅ Deploy frontend files to /var/www/html/hm-ems-report/
• ✅ Configure systemd service
• ✅ Start the application
• ✅ Run health checks

Updating the Application

To deploy updates:

cd /opt/hm_ems_report
git pull                # Pull latest code
sudo ./deploy.sh        # Deploy

The script is idempotent - it will:

• Backup data before updating
• Install/update Python dependencies
• Deploy frontend files
• Restart the service
• Verify everything is working

Managing the Service

Check Status

sudo systemctl status hm-ems

View Logs

# Real-time logs
sudo journalctl -u hm-ems -f

# Application logs
sudo tail -f /var/log/hm-ems-report/access.log
sudo tail -f /var/log/hm-ems-report/error.log

Restart Service

sudo systemctl restart hm-ems

Stop Service

sudo systemctl stop hm-ems

Start Service

sudo systemctl start hm-ems

Adding New Campaigns

1. Upload JSON file to /opt/hm-ems-data/Master_Json/:

   sudo cp new_campaign.json /opt/hm-ems-data/Master_Json/
   sudo chown vadym.samoilenko:vadym.samoilenko /opt/hm-ems-data/Master_Json/new_campaign.json
   

2. Upload campaign images to /opt/hm-ems-data/campaign_images/{year}/{campaign}/Automation_LR/:

   sudo mkdir -p /opt/hm-ems-data/campaign_images/2026/3045A/Automation_LR
   sudo cp images/*.jpg /opt/hm-ems-data/campaign_images/2026/3045A/Automation_LR/
   sudo chown -R vadym.samoilenko:vadym.samoilenko /opt/hm-ems-data/campaign_images/2026/
   

3. Refresh the web page - new campaign appears in dropdown

Accessing the Application

Once deployed, access the application at:

• Web UI: https://ai-sandbox.oliver.solutions/hm-ems-report/
• API: https://ai-sandbox.oliver.solutions/hm-ems-report/api/files

Troubleshooting

Service won't start

# Check service logs
sudo journalctl -u hm-ems -n 50

# Check if port is in use
sudo ss -tlnp | grep :5000

# Verify Python venv exists
ls -la /opt/hm_ems_report/venv/

API returns 502 Bad Gateway

• Service is not running: sudo systemctl start hm-ems
• Check Apache proxy config: sudo apachectl configtest
• Verify port 5000 is listening: sudo ss -tlnp | grep :5000

Images not loading

• Check directory permissions: ls -la /opt/hm-ems-data/campaign_images/
• Verify Apache alias configuration
• Check image paths in browser developer tools

No campaigns in dropdown

• Verify JSON files exist: ls -la /opt/hm-ems-data/Master_Json/
• Check file permissions (should be readable by vadym.samoilenko)
• Check API response: curl http://localhost:5000/api/files

Rollback

If deployment fails, rollback:

cd /opt/hm_ems_report
sudo git reset --hard HEAD~1
sudo ./deploy.sh

Restore data from backup:

cd /opt/hm-ems-data/backups
# Find latest backup
ls -lt | head -5

# Restore
sudo tar -xzf backup_YYYYMMDD_HHMMSS.tar.gz -C /opt/hm-ems-data/

Security Recommendations

Add HTTP Basic Authentication (Optional)

Edit Apache config:

<Location /hm-ems>
    AuthType Basic
    AuthName "H&M EMS Access"
    AuthUserFile /etc/apache2/.htpasswd
    Require valid-user
</Location>

Create password file:

sudo htpasswd -c /etc/apache2/.htpasswd admin
sudo systemctl restart apache2

SSL Configuration

The application runs on HTTPS at ai-sandbox.oliver.solutions. SSL should already be configured via Let's Encrypt.

To verify SSL certificate:

sudo certbot certificates

To renew SSL certificate:

sudo certbot renew --dry-run

Backup Strategy

The deployment script automatically creates backups in /opt/hm-ems-data/backups/ before each update.

Manual backup:

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
sudo tar -czf /opt/hm-ems-data/backups/manual_backup_${TIMESTAMP}.tar.gz \
    -C /opt/hm-ems-data Master_Json campaign_images

Monitoring

Set up monitoring for:

• Service status: systemctl is-active hm-ems
• Port availability: ss -tlnp | grep :5000
• Disk space: /opt/hm-ems-data and /var/log/hm-ems
• Log errors: /var/log/hm-ems-report/error.log

Support

For issues or questions, check:

• Application logs: /var/log/hm-ems-report/
• Systemd logs: sudo journalctl -u hm-ems
• Apache logs: /var/log/apache2/