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

```bash
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

```bash
# 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

```bash
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

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

#### 2. Configure Environment

```bash
cp .env.example .env
nano .env
```

Edit `.env` for your setup:
```bash
# 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

```bash
# 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

```bash
# 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
```bash
./scripts/launch-kiosk.sh
```

Option B: Auto-start on boot
```bash
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

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Restart all
docker-compose restart

# Restart specific service
docker-compose restart frontend

# Restart kiosk
sudo systemctl restart hotel-pi-kiosk
```

### Database Maintenance

```bash
# 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:
  ```bash
  # /etc/cron.d/hotel-pi-backup
  0 2 * * * pi /home/pi/hotel-pi/scripts/backup.sh
  ```
- [ ] Configure log rotation:
  ```bash
  # /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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Check available memory
free -h

# Monitor usage
watch -n 1 free -h

# Restart all services to free memory
docker-compose restart
```

## Security Hardening

### Network

```bash
# 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

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

sudo systemctl restart ssh
```

### Database

```bash
# Change default Directus password
# via admin panel in Directus

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

### Directus

```bash
# 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

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