# 🚀 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?](#-why-no-docker)
- [Prerequisites](#-prerequisites)
- [Installation Steps](#-installation-steps)
- [Service Management](#-service-management)
- [Monitoring & Maintenance](#-monitoring--maintenance)
- [Troubleshooting](#-troubleshooting)
- [Performance Optimization](#-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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Pull latest changes (if using git)
git pull

# Update the deployment
sudo ./deploy_rpi.sh update
```

### Uninstall

```bash
# Complete removal
sudo ./deploy_rpi.sh uninstall
```

## 📊 Monitoring & Maintenance

### Using the Monitor Script

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**
```bash
sudo nano /etc/dphys-swapfile
# Set: CONF_SWAPSIZE=256
sudo dphys-swapfile setup
sudo dphys-swapfile swapon
```

2. **Disable Unnecessary Services**
```bash
# 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**
```bash
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**
```bash
# 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

```bash
# 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**
```bash
passwd
```

2. **Configure Firewall**
```bash
sudo apt-get install ufw
sudo ufw allow 22/tcp  # SSH
sudo ufw allow 8000/tcp  # Application
sudo ufw enable
```

3. **SSH Key Authentication**
```bash
# 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**
```bash
# 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

```bash
# 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.