Hotel Pi - Quick Reference
Quick Start (Copy & Paste)
On Your Computer (First Time)
# Clone repository
git clone https://github.com/youruser/hotel-pi.git
cd hotel-pi
# Create environment file
cp .env.example .env
# Edit if needed
nano .env
# Start all services (requires Docker)
docker-compose up -d
# Wait ~30 seconds for services to start
# Access services
# Frontend: http://localhost:5173
# Directus CMS: http://localhost:8055
# Control: ws://localhost:3001
On Raspberry Pi (First Time)
# SSH into Pi
ssh pi@raspberrypi.local
# Clone and navigate
cd /home/pi
git clone https://github.com/youruser/hotel-pi.git
cd hotel-pi
# Run initialization (installs everything)
chmod +x scripts/init-system.sh
./scripts/init-system.sh
# Copy configuration
cp .env.example .env
nano .env
# Edit:
# VITE_API_URL=http://hotel-pi.local:8055
# VITE_WS_URL=ws://hotel-pi.local:3001
# WELCOME_NAME=Room 101 (or whatever)
# Start services
docker-compose up -d
# Wait 30 seconds
# Launch kiosk
./scripts/launch-kiosk.sh
Common Commands
Start/Stop Services
# Start all
docker-compose up -d
# Stop all
docker-compose down
# Restart specific service
docker-compose restart frontend
# View status
docker-compose ps
# View logs (all services)
./scripts/logs.sh all
# View logs (specific)
./scripts/logs.sh frontend
./scripts/logs.sh control
Frontend Development
cd frontend
npm install
npm run dev
# Runs on http://localhost:5173 with hot reload
Control Service Development
cd control-service
npm install
npm run dev
# Runs WebSocket server on port 3001
CMS Administration
- Open http://localhost:8055
- Create admin account (first time)
- Go to Collections
- Create "restaurants" and "attractions" collections
- Add content
- Enable public access (Settings → Roles & Permissions)
Rebuild Everything
./scripts/rebuild.sh
File Structure at a Glance
Hotel_Pi/
├── frontend/ ← Kiosk UI (Svelte)
├── control-service/ ← Remote control (Node.js)
├── directus/ ← CMS configuration
├── scripts/ ← Automation scripts
├── docker-compose.yml ← Service orchestration
├── .env.example ← Configuration template
├── README.md ← Overview
├── GETTING_STARTED.md ← Setup guide
├── DEPLOYMENT.md ← Production guide
├── API.md ← API reference
└── ARCHITECTURE.md ← Technical details
Configuration Quick Reference
.env Variables
# Frontend
VITE_API_URL=http://localhost:8055
VITE_WS_URL=ws://localhost:3001
WELCOME_NAME=Guest
IDLE_TIMEOUT_MINUTES=5
# Database (change these in production!)
POSTGRES_PASSWORD=directus123
DB_PASSWORD=directus123
SECRET=change-me
AUTH_SECRET=change-me
Keyboard/Remote Controls
In Kiosk
| Action |
Keyboard |
Remote |
| Navigate |
Arrow keys |
Arrow buttons |
| Select |
Enter |
OK/Select |
| Back |
Escape, Backspace |
Back/Exit |
| Wake idle |
Any key |
Any button |
Troubleshooting Cheat Sheet
| Problem |
Solution |
| Services won't start |
docker-compose logs → check errors |
| Frontend not loading |
Verify VITE_API_URL in .env |
| Images not showing |
Check Directus images are uploaded |
| Control service not responding |
curl http://localhost:3001/health |
| Remote not working |
Check TV CEC is enabled + cec-client installed |
Health Checks
# Frontend running?
curl http://localhost:5173
# Directus running?
curl http://localhost:8055/server/health | jq .
# Control service running?
curl http://localhost:3001/health | jq .
# Database connected?
docker-compose exec postgres pg_isready -U directus
# All services?
docker-compose ps
Useful Scripts
./scripts/launch-kiosk.sh # Start kiosk fullscreen
./scripts/rebuild.sh # Clean rebuild
./scripts/logs.sh all # View all logs
./scripts/logs.sh frontend # View frontend logs
./scripts/logs.sh control # View control logs
./scripts/stop.sh # Stop all services
./scripts/control.sh health # Check service health
Development Tips
Hot Reload Frontend
cd frontend
npm run dev
# Changes auto-reload, keep window open
Hot Reload Control Service
cd control-service
npm run dev
# Service restarts on file changes
Test WebSocket
npm install -g wscat
wscat -c ws://localhost:3001
# Type: {"type":"ping","payload":{}}
# Response: {"type":"pong",...}
Add New Restaurant
- Open http://localhost:8055
- Collections → Restaurants
- "+ Create Item"
- Fill details, upload image
- Publish
- Changes appear in kiosk immediately
Production Checklist
Performance Tuning (Raspberry Pi)
# Monitor resources
htop
# Check CPU temp
vcgencmd measure_temp
# Reduce UI animations (if slow)
# Edit frontend CSS, reduce animation durations
# Reduce database load
# Implement caching in control service
Backup & Restore
Quick Backup
docker-compose exec postgres pg_dump -U directus directus > backup.sql
tar -czf hotel-pi-backup.tar.gz .env backup.sql
Quick Restore
tar -xzf hotel-pi-backup.tar.gz
docker-compose exec -T postgres psql -U directus directus < backup.sql
Emergency Procedures
Kiosk Frozen?
# SSH in from another machine
ssh pi@hotel-pi.local
# Kill Chromium
pkill -f chromium
# Restart kiosk
./scripts/launch-kiosk.sh
Database Corrupt?
# Stop services
docker-compose down
# Restore from backup
docker-compose exec -T postgres psql -U directus directus < backup.sql
# Restart
docker-compose up -d
Complete Reset
# WARNING: Deletes all data
docker-compose down
docker volume rm hotel_pi_postgres_data
docker-compose up -d
# Requires Directus setup again
Useful Links
Getting Help
- Check service logs:
./scripts/logs.sh all
- Review documentation in README files
- Check .env configuration
- Verify all services are running:
docker-compose ps
- Test connectivity:
curl http://localhost:5173
Key Concepts
| Term |
Meaning |
| Kiosk |
Fullscreen app, no UI chrome |
| CMS |
Content Management System (Directus) |
| REST API |
HTTP-based data endpoint |
| WebSocket |
Real-time bidirectional communication |
| CEC |
Consumer Electronics Control (remote via HDMI) |
| Docker |
Containerization platform |
| Svelte |
Frontend framework |
| Node.js |
JavaScript runtime |
Version: 1.0.0 | Last Updated: March 2024 | Status: Production Ready
