hotel_pi/DEPLOYMENT.md

Deployment Guide

Raspberry Pi Deployment

Hardware Requirements

• Raspberry Pi 4/5 (2GB RAM minimum, 4GB recommended)
• Power Supply: 5V 3A minimum
• microSD Card: 16GB minimum
• HDMI Cable: for TV connection
• Network: Ethernet or WiFi
• Optional: HDMI-CEC compatible remote

System Preparation

1. Install Operating System

Download Raspberry Pi OS Lite:

# On your computer
wget https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2024-03-15.img.xz
xz -d raspios_lite_arm64-2024-03-15.img.xz

# Flash to microSD card (macOS)
diskutil list
diskutil unmountDisk /dev/disk2
sudo dd if=raspios_lite_arm64-2024-03-15.img of=/dev/rdisk2 bs=4m
diskutil eject /dev/disk2

2. Boot and Configure

Insert microSD, power on, and SSH:

ssh pi@raspberrypi.local
# Default password: raspberry

# Change password
passwd

# Set hostname
sudo raspi-config
# Network Options → N1 Hostname → hotel-pi

# Reboot
sudo reboot

3. Update System

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y \
  git \
  curl \
  wget \
  net-tools \
  htop \
  vim

Docker Installation

Install Docker & Compose

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group (no sudo needed)
sudo usermod -aG docker pi

# Log out and back in
exit
ssh pi@hotel-pi.local

# Verify
docker --version
docker run hello-world

Install Docker Compose

sudo apt-get install -y docker-compose

# Or use pip
sudo apt-get install -y python3-pip
sudo pip3 install docker-compose

# Verify
docker-compose --version

Application Deployment

1. Clone Repository

cd /home/pi
git clone https://github.com/youruser/hotel-pi.git
cd hotel-pi

2. Configure Environment

cp .env.example .env
nano .env

Edit .env for your setup:

# Network
VITE_API_URL=http://hotel-pi.local:8055
VITE_WS_URL=ws://hotel-pi.local:3001

# Customization
WELCOME_NAME="Room 101"
IDLE_TIMEOUT_MINUTES=10

# Database (change in production!)
POSTGRES_PASSWORD=<strong-password>
DB_PASSWORD=<strong-password>
SECRET=<random-secret>
AUTH_SECRET=<random-secret>

3. Install System Dependencies

# Run initialization script (handles everything)
chmod +x scripts/init-system.sh
./scripts/init-system.sh

# Or manually:
sudo apt-get install -y chromium-browser libcec-dev

4. Start Services

# First time startup (initializes database)
docker-compose up -d

# Wait for services to initialize (30-60 seconds)
docker-compose ps

# Should see all services as "Up"

5. Initialize Directus

Visit http://hotel-pi.local:8055 in your browser:

1. Set Admin Account: Email and password
2. Create Collections: (see directus/README.md)
   • Restaurants
   • Attractions
3. Add Content: Use admin panel to add restaurants and attractions
4. Enable Public Access: Settings → Roles & Permissions

6. Launch Kiosk

Option A: Manual start

./scripts/launch-kiosk.sh

Option B: Auto-start on boot

sudo systemctl enable hotel-pi-kiosk
sudo systemctl start hotel-pi-kiosk
sudo systemctl status hotel-pi-kiosk

# View logs
journalctl -u hotel-pi-kiosk -f

Post-Deployment

1. Verify All Services

# Check Docker containers
docker-compose ps

# Check control service
curl http://localhost:3001/health | jq .

# Check Directus
curl http://localhost:8055/server/health | jq .

# Test WebSocket
wscat -c ws://localhost:3001

2. Test Navigation

In the kiosk:

1. Press any key to wake from idle
2. Navigate home menu with arrow keys
3. Test each section
4. Verify images and content load
5. Test "Watch Plex" (may not launch if Plex not installed)

3. Configure HDMI-CEC

1. Ensure TV supports CEC and it's enabled
2. Power on TV and connect remote
3. Test remote input from kiosk
4. Check logs: ./scripts/logs.sh control

4. Performance Tuning

Raspberry Pi specific optimizations:

# Reduce GPU memory (if using lite OS)
sudo raspi-config
# Advanced Options → GPU Memory → 64MB

# Enable hardware video decoding
# Already enabled in Chromium by default

# Monitor performance
sudo apt-get install -y htop
htop

# Check temperatures
vcgencmd measure_temp

Backup & Recovery

Backup Directus Data

# Export database
docker-compose exec postgres pg_dump -U directus directus > directus-backup.sql

# Export uploads
docker cp hotel_pi_cms:/directus/uploads ./uploads-backup

# Create full snapshot
tar -czf hotel-pi-backup-$(date +%Y%m%d).tar.gz \
  directus-backup.sql \
  uploads-backup/ \
  .env

Restore from Backup

# Restore database
docker-compose exec -T postgres psql -U directus directus < directus-backup.sql

# Restore uploads
docker cp uploads-backup/. hotel_pi_cms:/directus/uploads
docker-compose restart directus

# Restore .env
cp .env.backup .env
docker-compose restart

Updates & Maintenance

Update Application

# Pull latest code
git pull origin main

# Rebuild containers
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# Migration if needed
docker-compose exec directus directus database migrate:latest

Update CMS Content

Use Directus admin panel (no downtime needed)

Monitor Logs

# Real-time logs
./scripts/logs.sh all

# Specific service
./scripts/logs.sh frontend
./scripts/logs.sh control

# System logs
journalctl -u hotel-pi-kiosk -f

# Database logs
docker-compose logs postgres

Restart Services

# Restart all
docker-compose restart

# Restart specific service
docker-compose restart frontend

# Restart kiosk
sudo systemctl restart hotel-pi-kiosk

Database Maintenance

# Backup before maintenance
./scripts/backup.sh

# Connect to PostgreSQL
docker-compose exec postgres psql -U directus directus

# Vacuum (optimize)
VACUUM ANALYZE;

# Check constraints
\d restaurants
\d attractions

Production Checklist

• Change all default passwords in .env
• Set SECRET and AUTH_SECRET to strong random values
• Configure CORS_ORIGIN for your domain
• Set up HTTPS (if accessing remotely)
• Set up backup cron job:

  # /etc/cron.d/hotel-pi-backup
  0 2 * * * pi /home/pi/hotel-pi/scripts/backup.sh
  

• Configure log rotation:

  # /etc/logrotate.d/hotel-pi
  /tmp/hotel_pi*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
  }
  

• Set up monitoring/alerts
• Test recovery procedure
• Document custom configuration
• Create admin account backup
• Test Plex integration (if used)
• Verify CEC remote works consistently

Troubleshooting

Services Won't Start

# Check status
docker-compose ps

# View error logs
docker-compose logs --tail=50 frontend
docker-compose logs --tail=50 postgres

# Restart from scratch
docker-compose down
docker-compose up -d

# Check resources
free -h
df -h
htop

Kiosk Crashes

# Manual restart
./scripts/launch-kiosk.sh

# Check logs
journalctl -u hotel-pi-kiosk --since "10 minutes ago"

# Restart service
sudo systemctl restart hotel-pi-kiosk

Directus Not Accessible

# Verify container is running
docker-compose ps | grep directus

# Check database connection
docker-compose exec directus directus version

# Restart service
docker-compose restart directus postgres

Network Issues

# Check connectivity
ping 8.8.8.8
ping hotel-pi.local

# Check Docker network
docker network ls
docker network inspect hotel_pi_network

# Restart networking
docker-compose down
sudo systemctl restart docker
docker-compose up -d

Memory Issues

# Check available memory
free -h

# Monitor usage
watch -n 1 free -h

# Restart all services to free memory
docker-compose restart

Security Hardening

Network

# Firewall rules
sudo ufw enable
sudo ufw allow 22      # SSH
sudo ufw allow 8055    # Directus (restrict to local if possible)
sudo ufw allow 5173    # Frontend (restrict to local)
sudo ufw allow 3001    # Control (restrict to local)

SSH

# Disable password auth
sudo nano /etc/ssh/sshd_config
# Set: PasswordAuthentication no
# Set: PermitRootLogin no

sudo systemctl restart ssh

Database

# Change default Directus password
# via admin panel in Directus

# Change PostgreSQL password
docker-compose exec postgres psql -U directus -d directus
\password directus

Directus

# Change SECRET and AUTH_SECRET in .env
# Regenerate with: openssl rand -base64 32

# Configure authentication if public facing
# Settings → Authentication → Providers

Support

• Documentation: See main README.md and GETTING_STARTED.md
• API Reference: See API.md
• Frontend Guide: See frontend/README.md
• Control Service: See control-service/README.md
• CMS Setup: See directus/README.md

Emergency Procedures

Hard Reset

# Stop everything
docker-compose down

# Clear database (WARNING: Deletes all data)
docker volume rm hotel_pi_postgres_data

# Clear uploads
rm -rf docker volumes/uploads

# Restart fresh
docker-compose up -d

SSH Access (if kiosk frozen)

Kiosk Chromium may hang. Always maintain SSH access:

# From remote machine
ssh pi@hotel-pi.local

# Kill frozen Chromium
pkill -f chromium

# Restart
./scripts/launch-kiosk.sh

Power Cycle

If all else fails:

1. Power off Raspberry Pi (hold power 10 seconds)
2. Power back on
3. SSH in and check services
4. Restart as needed