Sanitized mirror from private repository - 2026-04-20 01:32:01 UTC

docs/infrastructure/hosts/rpi5-runbook.md

@@ -0,0 +1,179 @@
+# RPi5 Runbook
+
+*Raspberry Pi 5 - Edge Services*
+
+**Endpoint ID:** 443395  
+**Status:** 🟢 Online  
+**Hardware:** ARM Cortex-A76, 16GB RAM, 512GB USB SSD  
+**Access:** `rpi5-vish.local`
+
+---
+
+## Overview
+
+Raspberry Pi 5 runs edge services including Immich backup and lightweight applications.
+
+## Hardware Specs
+
+| Component | Specification |
+|----------|---------------|
+| Model | Raspberry Pi 5 |
+| CPU | ARM Cortex-A76 (4-core) |
+| RAM | 16GB |
+| Storage | 512GB USB-C SSD |
+| Network | 1x 1GbE (Pi 4 adapter) |
+
+## Services
+
+### Primary Services
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| **Immich** | 2283 | Photo backup (edge) |
+| Portainer Agent | 9001 | Container management |
+| Node Exporter | 9100 | Metrics |
+
+### Services (if enabled)
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| Plex | 32400 | Media server |
+| WireGuard | 51820 | VPN |
+
+## Secondary Pi Nodes
+
+### Pi-5-Kevin
+This is a secondary Raspberry Pi 5 node with identical specifications but not typically online.
+
+- **CPU**: Broadcom BCM2712 (4-core, 2.4GHz)
+- **RAM**: 8GB LPDDR4X
+- **Storage**: 64GB microSD
+- **Network**: Gigabit Ethernet + WiFi 6
+
+---
+
+## Daily Operations
+
+### Check Service Health
+```bash
+# Via Portainer
+open http://rpi5-vish.local:9001
+
+# Via SSH
+ssh pi@rpi5-vish.local
+docker ps
+```
+
+### Immich Status
+```bash
+# Access UI
+open http://rpi5-vish.local:2283
+
+# Check sync status
+docker logs immich-server | grep -i sync
+```
+
+---
+
+## Common Issues
+
+### Container Won't Start (ARM compatibility)
+1. Verify image supports ARM64: `docker pull --platform linux/arm64 <image>`
+2. Check container logs
+3. Verify Raspberry Pi OS 64-bit
+
+### Storage Slow
+1. Check USB drive: `lsusb`
+2. Verify SSD: `sudo hdparm -t /dev/sda`
+3. Use fast USB port (USB-C)
+
+### Network Issues
+1. Check adapter compatibility
+2. Verify driver loaded: `lsmod | grep smsc95xx`
+3. Update firmware: `sudo rpi-eeprom-update`
+
+---
+
+## Storage
+
+### Layout
+```
+/home/pi/
+├── docker/           # Docker data
+├── immich/          # Photo storage
+└── backups/         # Local backups
+```
+
+### Performance Tips
+- Use USB 3.0 SSD
+- Usequality power supply (5V 5A)
+- Enable USB max_current in config.txt
+
+---
+
+## Maintenance
+
+### Weekly
+- [ ] Check Docker disk usage
+- [ ] Verify Immich backup
+- [ ] Check container health
+
+### Monthly
+- [ ] Update Raspberry Pi OS
+- [ ] Clean unused images
+- [ ] Review resource usage
+
+### Quarterly
+- [ ] Test backup restoration
+- [ ] Verify ARM image compatibility
+- [ ] Check firmware updates
+
+---
+
+## Emergency Procedures
+
+### SD Card/Storage Failure
+1. Replace storage drive
+2. Reinstall Raspberry Pi OS
+3. Run deploy playbook:
+   ```bash
+   ansible-playbook ansible/homelab/playbooks/deploy_rpi5_vish.yml
+   ```
+
+### Overheating
+1. Add heatsinks
+2. Enable fan
+3. Reduce CPU frequency: `sudo echo "arm_freq=1800" >> /boot/config.txt`
+
+## Notes
+
+This Raspberry Pi 5 system is the primary node that runs Immich and other services, with the secondary node **pi-5-kevin** intentionally kept offline for backup purposes when needed.
+
+---
+
+## Useful Commands
+
+```bash
+# SSH access
+ssh pi@rpi5-vish.local
+
+# Check temperature
+vcgencmd measure_temp
+
+# Check throttling
+vcgencmd get_throttled
+
+# Update firmware
+sudo rpi-eeprom-update
+sudo rpi-eeprom-update -a
+
+# View Immich logs
+docker logs -f immich-server
+```
+
+---
+
+## Links
+
+- [Immich](http://rpi5-vish.local:2283)
+- [Portainer](http://rpi5-vish.local:9001)