Commit All
This commit is contained in:
422
DEPLOY_README.md
Normal file
422
DEPLOY_README.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# 🚀 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.
|
||||
Reference in New Issue
Block a user