plex-restart/PROJECT_GUIDE.md

Project Structure

plex-restart/
├── monitor.py              # Main monitoring agent
├── Dockerfile              # Container definition
├── docker-compose.yml      # Service orchestration
├── requirements.txt        # Python dependencies
├── test_gpio.py           # GPIO testing utility
├── health_check.py        # Service health monitor
├── .env.example           # Configuration template
├── INSTALL_NATIVE.md      # Native installation guide
├── README.md              # Complete documentation
└── .gitignore             # Git ignore rules

Quick Reference

Deploy (Docker Compose)

cp .env.example .env
# Edit .env with your host IP and GPIO pin
docker-compose up -d
docker-compose logs -f

Deploy (Native)

See INSTALL_NATIVE.md for systemd service or manual installation.

Test GPIO

POWER_BUTTON_GPIO=17 python3 test_gpio.py

Check Health

python3 health_check.py

View Logs

# Docker
docker-compose logs -f pikvm-monitor

# Native/systemd
journalctl -u pikvm-monitor -f
tail -f /var/log/pikvm-monitor.log

Key Parameters

• Ping Interval: 180 seconds (3 minutes)
• Downtime Threshold: 15 minutes (5 failed pings)
• Long Press: 5 seconds (power down)
• Wait: 90 seconds (cool-down)
• Short Press: 1 second (power on)

Adjust in .env as needed for faster/slower recovery.

Files Overview

File	Purpose
monitor.py	Main monitoring loop with GPIO control
Dockerfile	Builds container image
docker-compose.yml	Defines service with volume/env mapping
requirements.txt	Python package versions
test_gpio.py	Tests GPIO pin configuration
health_check.py	Verifies monitor is running
.env.example	Configuration template
INSTALL_NATIVE.md	Systemd/manual setup

Architecture

PiKVM (Runs Docker Compose)
  └── pikvm-monitor Container
       ├── Pings HOST_IP every 3 min
       ├── Falls back to GATEWAY_IP
       ├── Tracks consecutive failures
       ├── After 15 min downtime:
       │   ├── Long press GPIO (5 sec) → Power down
       │   ├── Wait 90 seconds
       │   └── Short press GPIO (1 sec) → Power on
       └── Logs to /var/log/pikvm-monitor.log

Next Steps

1. Configure: Edit .env with your IPs and GPIO pin
2. Test GPIO: Run test_gpio.py to verify pin works
3. Deploy: Use docker-compose up -d
4. Monitor: Check logs with docker-compose logs -f
5. Verify: Run health_check.py periodically

Support

• PiKVM Docs: https://docs.pikvm.org/
• gpiozero: https://gpiozero.readthedocs.io/
• Docker Compose: https://docs.docker.com/compose/