homelab-optimized/docs/infrastructure/hosts/rpi5-runbook.md

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

# Via Portainer
open http://rpi5-vish.local:9001

# Via SSH
ssh pi@rpi5-vish.local
docker ps

Immich Status

# 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:

   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

# 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
• Portainer