422 lines
8.7 KiB
Markdown
422 lines
8.7 KiB
Markdown
# 🚀 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. |