hvac-kia-content/DEPLOY.md

Deployment Instructions

Prerequisites

Ensure the following are completed:

1. Python environment is set up with uv
2. All dependencies installed: uv pip install -r requirements.txt
3. .env file configured with API credentials
4. Test run successful: uv run python run_api_production_v2.py

Deploy to Production

Option 1: Automated Installation (Recommended)

cd /home/ben/dev/hvac-kia-content/deploy
sudo ./install.sh

This will:

• Copy systemd service files to /etc/systemd/system/
• Enable and start the timers
• Show service status

Option 2: Manual Installation

# Copy service files
sudo cp deploy/*.service /etc/systemd/system/
sudo cp deploy/*.timer /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable timers (start on boot)
sudo systemctl enable hvac-content-8am.timer
sudo systemctl enable hvac-content-12pm.timer

# Start timers immediately
sudo systemctl start hvac-content-8am.timer
sudo systemctl start hvac-content-12pm.timer

Verify Deployment

Check timer status:

systemctl list-timers | grep hvac

Expected output:

NEXT                         LEFT          LAST  PASSED  UNIT                      ACTIVATES
Mon 2025-08-20 08:00:00 ADT 21h left      n/a   n/a     hvac-content-8am.timer    hvac-content-8am.service
Mon 2025-08-19 12:00:00 ADT 1h 9min left  n/a   n/a     hvac-content-12pm.timer   hvac-content-12pm.service

Monitor Services

View logs in real-time:

# Morning run logs
journalctl -u hvac-content-8am -f

# Noon run logs
journalctl -u hvac-content-12pm -f

# All logs
journalctl -u hvac-content-* -f

Manual Testing

Run the service manually:

# Test morning run
sudo systemctl start hvac-content-8am.service

# Check status
sudo systemctl status hvac-content-8am.service

Stop/Disable Services

If needed:

# Stop timers
sudo systemctl stop hvac-content-8am.timer
sudo systemctl stop hvac-content-12pm.timer

# Disable from starting on boot
sudo systemctl disable hvac-content-8am.timer
sudo systemctl disable hvac-content-12pm.timer

Troubleshooting

Service Fails to Start

1. Check logs: journalctl -u hvac-content-8am -n 50
2. Verify paths in service files
3. Check Python environment: source .venv/bin/activate && python --version
4. Test manual run: cd /home/ben/dev/hvac-kia-content && uv run python run_api_production_v2.py

Permission Issues

• Ensure user ben has read/write access to data directories
• Check NAS mount permissions: ls -la /mnt/nas/hvacknowitall/

Timer Not Triggering

• Check timer status: systemctl status hvac-content-8am.timer
• Verify system time: timedatectl
• Check timer schedule: systemctl cat hvac-content-8am.timer

Schedule

The system runs automatically at:

• 8:00 AM ADT - Morning content aggregation
• 12:00 PM ADT - Noon content aggregation

Both runs will:

1. Fetch new content from all sources
2. Merge with existing cumulative files
3. Update metrics and add captions where available
4. Archive previous versions
5. Sync to NAS at /mnt/nas/hvacknowitall/