turmlibar-calendar/DEPLOY_README.md

🚀 Raspberry Pi Deployment Guide - Turmli Bar Calendar

This guide provides complete instructions for deploying the Turmli Bar Calendar application on a Raspberry Pi (optimized for Pi Zero) as a systemd service without Docker.

📋 Table of Contents

• Why No Docker?
• Prerequisites
• Installation Steps
• Service Management
• Monitoring & Maintenance
• Troubleshooting
• Performance Optimization

🎯 Why No Docker?

On a Raspberry Pi Zero (512MB RAM, single-core ARM CPU), running without Docker provides:

• 50-100MB less RAM usage (no Docker daemon)
• Faster startup times (no container overhead)
• Better performance (direct execution)
• Simpler debugging (direct access to processes)
• Native systemd integration (better logging and management)

📋 Prerequisites

Hardware

• Raspberry Pi Zero W or better
• 8GB+ SD card (Class 10 recommended)
• Stable 5V power supply
• Network connection (WiFi or Ethernet)

Software

• Raspberry Pi OS Lite (32-bit)
• Python 3.9+
• 150MB free RAM
• 200MB free storage

📦 Installation Steps

Step 1: Prepare Your Raspberry Pi

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

# Install Git (if not present)
sudo apt-get install git -y

# Create a working directory
mkdir -p ~/projects
cd ~/projects

Step 2: Get the Application

# Clone the repository
git clone <your-repository-url> turmli-calendar
cd turmli-calendar

# OR copy files from your development machine
# From your dev machine:
scp -r /home/belar/Code/turmli-bar-calendar-tool/* pi@<pi-ip>:~/projects/turmli-calendar/

Step 3: Run the Deployment Script

# Make the script executable
chmod +x deploy_rpi.sh

# Run the installation
sudo ./deploy_rpi.sh install

The script will:

1. Check system requirements
2. Install Python dependencies
3. Create /opt/turmli-calendar directory
4. Set up Python virtual environment
5. Install application dependencies
6. Create systemd service
7. Start the application

Step 4: Verify Installation

# Check service status
sudo systemctl status turmli-calendar

# Test the API
curl http://localhost:8000/api/events

# Check the web interface
# Open in browser: http://<pi-ip>:8000

🛠️ Service Management

Basic Commands

# Start the service
sudo ./deploy_rpi.sh start
# OR
sudo systemctl start turmli-calendar

# Stop the service
sudo ./deploy_rpi.sh stop
# OR
sudo systemctl stop turmli-calendar

# Restart the service
sudo ./deploy_rpi.sh restart
# OR
sudo systemctl restart turmli-calendar

# Check status
sudo ./deploy_rpi.sh status

# View logs
sudo ./deploy_rpi.sh logs
# OR
sudo journalctl -u turmli-calendar -f

Update Application

# Pull latest changes (if using git)
git pull

# Update the deployment
sudo ./deploy_rpi.sh update

Uninstall

# Complete removal
sudo ./deploy_rpi.sh uninstall

📊 Monitoring & Maintenance

Using the Monitor Script

# Quick health check
./deployment/monitor.sh status

# Full system report
./deployment/monitor.sh full

# Continuous monitoring (30s refresh)
./deployment/monitor.sh monitor

# Check resources only
./deployment/monitor.sh resources

Manual Monitoring

# Memory usage
free -h

# CPU temperature (Pi specific)
vcgencmd measure_temp

# Check for throttling
vcgencmd get_throttled

# Disk usage
df -h

# Process info
ps aux | grep turmli

Log Management

# View last 50 log entries
sudo journalctl -u turmli-calendar -n 50

# Follow logs in real-time
sudo journalctl -u turmli-calendar -f

# Export logs
sudo journalctl -u turmli-calendar > turmli-logs.txt

# Clear old logs (if needed)
sudo journalctl --vacuum-time=7d

🐛 Troubleshooting

Service Won't Start

# Check for Python errors
sudo -u pi /opt/turmli-calendar/venv/bin/python /opt/turmli-calendar/main.py

# Check permissions
ls -la /opt/turmli-calendar/

# Check port availability
sudo netstat -tlnp | grep 8000

# Review detailed logs
sudo journalctl -u turmli-calendar -n 100 --no-pager

High Memory Usage

# Restart the service
sudo systemctl restart turmli-calendar

# Check for memory leaks
watch -n 1 'free -h'

# Clear system cache
sudo sh -c 'echo 3 > /proc/sys/vm/drop_caches'

Application Not Responding

# Test locally
curl -v http://localhost:8000/api/events

# Check network
ip addr show
ping -c 4 google.com

# Restart networking
sudo systemctl restart networking

Calendar Not Updating

# Check cache file
ls -la /opt/turmli-calendar/calendar_cache.json

# Manually trigger update
curl -X POST http://localhost:8000/api/refresh

# Check external connectivity
curl -I https://outlook.live.com

⚡ Performance Optimization

For Raspberry Pi Zero

1. Increase Swap Space

sudo nano /etc/dphys-swapfile
# Set: CONF_SWAPSIZE=256
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

2. Disable Unnecessary Services

# Check what's running
systemctl list-units --type=service --state=running

# Disable unused services
sudo systemctl disable --now bluetooth
sudo systemctl disable --now cups
sudo systemctl disable --now avahi-daemon

3. Optimize Boot Configuration

sudo nano /boot/config.txt
# Add:
gpu_mem=16          # Minimize GPU memory
boot_delay=0        # Faster boot
disable_splash=1    # No splash screen

4. Set CPU Governor

# Check current governor
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

# Set to performance (optional, uses more power)
echo performance | sudo tee /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

Network Optimization

# Use static IP to reduce DHCP overhead
sudo nano /etc/dhcpcd.conf

# Add (adjust for your network):
interface wlan0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1 8.8.8.8

# Restart networking
sudo systemctl restart dhcpcd

📈 Expected Resource Usage

Component	Idle	Active	Peak
RAM	~80MB	~120MB	~150MB
CPU	2-5%	10-20%	40%
Disk	~200MB	~210MB	~250MB
Network	<1KB/s	5-10KB/s	50KB/s

🔒 Security Recommendations

1. Change Default Password

passwd

2. Configure Firewall

sudo apt-get install ufw
sudo ufw allow 22/tcp  # SSH
sudo ufw allow 8000/tcp  # Application
sudo ufw enable

3. SSH Key Authentication

# On your dev machine
ssh-copy-id pi@<pi-ip>

# On Pi, disable password auth
sudo nano /etc/ssh/sshd_config
# Set: PasswordAuthentication no
sudo systemctl restart ssh

4. Regular Updates

# Create update script
cat > ~/update-system.sh << 'EOF'
#!/bin/bash
sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get autoremove -y
sudo apt-get autoclean
EOF
chmod +x ~/update-system.sh

# Run monthly
crontab -e
# Add: 0 2 1 * * /home/pi/update-system.sh

📁 File Locations

Component	Path
Application	/opt/turmli-calendar/
Service File	/etc/systemd/system/turmli-calendar.service
Cache File	/opt/turmli-calendar/calendar_cache.json
Static Files	/opt/turmli-calendar/static/
Virtual Env	/opt/turmli-calendar/venv/
Logs	Journal (use journalctl)

🆘 Quick Reference

# Service control
sudo systemctl {start|stop|restart|status} turmli-calendar

# Logs
sudo journalctl -u turmli-calendar -f

# Test API
curl http://localhost:8000/api/events | python3 -m json.tool

# Check port
sudo netstat -tlnp | grep 8000

# Python packages
/opt/turmli-calendar/venv/bin/pip list

# Manual run (for debugging)
cd /opt/turmli-calendar
sudo -u pi ./venv/bin/python -m uvicorn main:app --host 0.0.0.0 --port 8000

# System resources
htop  # Install with: sudo apt-get install htop

📝 Notes

• The application runs on port 8000 by default
• Service automatically starts on boot
• Logs are managed by systemd journal
• Cache persists in /opt/turmli-calendar/calendar_cache.json
• The service runs as user pi for security
• Memory is limited to 256MB to prevent system crashes
• CPU is limited to 75% to keep system responsive

🤝 Support

If you encounter issues:

1. Check the logs first: sudo journalctl -u turmli-calendar -n 100
2. Run the monitor script: ./deployment/monitor.sh full
3. Try manual startup to see errors: cd /opt/turmli-calendar && sudo -u pi ./venv/bin/python main.py
4. Check system resources: free -h && df -h
5. Verify network connectivity: ping -c 4 google.com

📄 License

MIT License - See main project repository for details.