sandbox-reports/DEPLOYMENT.md

VEO3 Report System - Server Deployment Guide

This guide covers deploying the VEO3 report system as a systemd service that runs daily at 7:00 PM EST.

Overview

Instead of using cron, this system uses:

• Python Scheduler Daemon (veo3_scheduler.py) - Runs continuously and triggers reports at scheduled times
• systemd Service - Manages the scheduler, ensures it starts on boot and restarts if it crashes
• APScheduler - Python library for robust job scheduling with timezone support

Prerequisites

Server Requirements

• Linux server (Ubuntu 20.04+ or similar)
• Python 3.8 or higher
• systemd (standard on most modern Linux distributions)
• sudo/root access for initial setup

Required Files

veo3_report.py          - Report generation script
veo3_scheduler.py       - Scheduler daemon (NEW)
requirements.txt        - Python dependencies
.env                    - Configuration file with SMTP credentials
veo3-report.service     - systemd service definition
deploy.sh               - Automated deployment script

Quick Deploy

Option 1: Automated Deployment (Recommended)

1. Upload files to server:

   scp veo3_report.py veo3_scheduler.py requirements.txt .env \
       veo3-report.service deploy.sh \
       user@your-server:/tmp/veo3-deploy/
   

2. SSH into server:

   ssh user@your-server
   

3. Run deployment script:

   cd /tmp/veo3-deploy
   chmod +x deploy.sh
   sudo ./deploy.sh
   

The script will:

• ✅ Create /var/www/veo3-report directory
• ✅ Set up Python virtual environment
• ✅ Install all dependencies
• ✅ Configure systemd service
• ✅ Start the service
• ✅ Enable auto-start on boot

Option 2: Manual Deployment

1. Create deployment directory:

   sudo mkdir -p /var/www/veo3-report
   sudo mkdir -p /var/log/veo3-report
   

2. Copy files:

   sudo cp veo3_report.py veo3_scheduler.py requirements.txt .env /var/www/veo3-report/
   

3. Create virtual environment:

   cd /var/www/veo3-report
   sudo python3 -m venv venv
   sudo ./venv/bin/pip install -r requirements.txt
   

4. Set permissions:

   sudo chown -R www-data:www-data /var/www/veo3-report
   sudo chown -R www-data:www-data /var/log/veo3-report
   sudo chmod 600 /var/www/veo3-report/.env
   

5. Install systemd service:

   sudo cp veo3-report.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable veo3-report
   sudo systemctl start veo3-report
   

Service Management

Check Service Status

sudo systemctl status veo3-report

View Live Logs

# Systemd logs
sudo journalctl -u veo3-report -f

# Application logs
sudo tail -f /var/www/veo3-report/logs/veo3_scheduler.log

Start/Stop/Restart

sudo systemctl start veo3-report
sudo systemctl stop veo3-report
sudo systemctl restart veo3-report

Disable Auto-Start

sudo systemctl disable veo3-report

Force Immediate Report Run (Testing)

# Stop the service
sudo systemctl stop veo3-report

# Run manually to test
cd /var/www/veo3-report
sudo -u www-data ./venv/bin/python veo3_report.py

# Restart service
sudo systemctl start veo3-report

Configuration

Change Schedule Time

Edit /var/www/veo3-report/veo3_scheduler.py:

# Current: 7:00 PM EST
self.scheduler.add_job(
    self.run_report,
    trigger=CronTrigger(hour=19, minute=0, timezone=EST),  # Change hour (24hr format)
    ...
)

After editing, restart the service:

sudo systemctl restart veo3-report

Change Timezone

Edit veo3_scheduler.py:

# Change from EST to another timezone
EST = pytz.timezone('America/New_York')  # Change to your timezone
# Examples:
# PST: 'America/Los_Angeles'
# CST: 'America/Chicago'
# UTC: 'UTC'

Update SMTP Credentials

Edit /var/www/veo3-report/.env and restart:

sudo nano /var/www/veo3-report/.env
sudo systemctl restart veo3-report

Change Cost Per Video

Edit /var/www/veo3-report/veo3_report.py:

COST_PER_VIDEO = 3.20  # Change this value

Restart service after changes:

sudo systemctl restart veo3-report

Monitoring

Check Next Scheduled Run

sudo journalctl -u veo3-report --no-pager | grep "Next scheduled run"

View Recent Reports

ls -lh /var/www/veo3-report/email_report.html
cat /var/www/veo3-report/email_report.html

Check Email Delivery

sudo journalctl -u veo3-report --no-pager | grep "Email sent"

Troubleshooting

Service Won't Start

# Check for errors
sudo journalctl -u veo3-report -n 50

# Check service file syntax
sudo systemd-analyze verify veo3-report.service

# Check Python dependencies
cd /var/www/veo3-report
sudo -u www-data ./venv/bin/pip list

Reports Not Sending

# Test SMTP credentials
cd /var/www/veo3-report
sudo -u www-data ./venv/bin/python veo3_report.py

# Check email logs
sudo journalctl -u veo3-report | grep -i smtp
sudo journalctl -u veo3-report | grep -i email

Wrong Timezone

# Check server timezone
timedatectl

# The service uses EST timezone explicitly in the code,
# regardless of server timezone

Permission Errors

# Fix ownership
sudo chown -R www-data:www-data /var/www/veo3-report
sudo chown -R www-data:www-data /var/log/veo3-report

# Fix .env permissions
sudo chmod 600 /var/www/veo3-report/.env

Log Files

File	Purpose
/var/log/veo3-report/service.log	Service stdout
/var/log/veo3-report/service-error.log	Service stderr
/var/www/veo3-report/logs/veo3_scheduler.log	Scheduler application log
journalctl -u veo3-report	Systemd service log

Updating the System

1. Stop the service:

   sudo systemctl stop veo3-report
   

2. Update files:

   sudo cp new_veo3_report.py /var/www/veo3-report/veo3_report.py
   

3. Update dependencies if needed:

   cd /var/www/veo3-report
   sudo ./venv/bin/pip install -r requirements.txt
   

4. Restart service:

   sudo systemctl restart veo3-report
   

Uninstall

# Stop and disable service
sudo systemctl stop veo3-report
sudo systemctl disable veo3-report

# Remove service file
sudo rm /etc/systemd/system/veo3-report.service
sudo systemctl daemon-reload

# Remove application files
sudo rm -rf /var/www/veo3-report
sudo rm -rf /var/log/veo3-report

Architecture Benefits

Why systemd service instead of cron?

✅ Better process management - Service restarts automatically if it crashes ✅ Centralized logging - All logs in one place via journalctl ✅ Dependency handling - Waits for network before starting ✅ Status monitoring - Easy to check if service is running ✅ Resource control - Can set CPU/memory limits if needed ✅ Boot integration - Starts automatically on server reboot ✅ Timezone handling - Explicit timezone support in Python, not relying on server TZ

Support

For issues or questions:

1. Check logs: sudo journalctl -u veo3-report -n 100
2. Test manually: cd /var/www/veo3-report && sudo -u www-data ./venv/bin/python veo3_report.py
3. Review .env configuration
4. Verify SMTP credentials are correct