hotel_pi/GETTING_STARTED.md

Getting Started with Hotel Pi

Quick Start (5 minutes)

1. Prerequisites

• Docker & Docker Compose installed
• Node.js 18+ (for local development)
• Git

2. Clone & Setup

cd /path/to/Hotel_Pi
cp .env.example .env

3. Start Services

docker-compose up -d

Wait for all services to be healthy:

docker-compose ps

4. Access the System

Service	URL	Purpose
Frontend	http://localhost:5173	Kiosk UI
Directus CMS	http://localhost:8055	Content management
Control Service	ws://localhost:3001	Remote control

Development Setup

Run Frontend Locally

cd frontend
npm install
npm run dev

Frontend will be available at http://localhost:5173

Run Control Service Locally

cd control-service
npm install
npm run dev

WebSocket available at ws://localhost:3001

Docker Development Mode

Use the dev override file:

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

This enables hot-reload for both frontend and control service.

Directus CMS Setup

1. Access Directus: http://localhost:8055

2. Create admin account (first time setup)

3. Create collections:

   • See directus/README.md for detailed collection schema
   • Restaurants (name, description, cuisine_type, image, website_url)
   • Attractions (name, description, category, distance_km, image)

4. Add content: Use Directus admin panel to add restaurants and attractions

5. Enable public access:

   • Settings → Roles & Permissions
   • Create "Public" role with read access to collections

Testing & Navigation

Keyboard Controls (Development)

• Arrow Keys - Navigate menu
• Enter - Select item
• Escape/Backspace - Go back
• Any key - Wake from idle screen

Remote Control (Hardware)

HDMI-CEC compatible remotes will work automatically once connected.

The control service translates CEC codes to navigation events.

Raspberry Pi Deployment

System Setup

# Run initialization script
./scripts/init-system.sh

This will:

• Install system dependencies
• Set up Docker
• Configure HDMI-CEC
• Create systemd service
• Enable auto-startup

Configure Environment

Edit .env with Raspberry Pi specifics:

# .env
VITE_API_URL=http://raspberrypi.local:8055
VITE_WS_URL=ws://raspberrypi.local:3001
WELCOME_NAME=Guest Room 101
IDLE_TIMEOUT_MINUTES=10

Deploy

# Build and restart services
./scripts/rebuild.sh

# Start kiosk immediately
./scripts/launch-kiosk.sh

# Or enable auto-start
sudo systemctl start hotel-pi-kiosk
sudo systemctl status hotel-pi-kiosk

View Logs

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

# Docker logs
./scripts/logs.sh all

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

Common Tasks

Add New Restaurant

1. Open Directus: http://localhost:8055
2. Go to Collections → Restaurants
3. Click "+ Create Item"
4. Fill in details (name, description, image, etc.)
5. Publish
6. Changes appear in kiosk immediately

Modify Idle Screen Message

Edit .env:

WELCOME_NAME="Welcome, Guest"
IDLE_TIMEOUT_MINUTES=5

Then restart frontend:

docker-compose restart frontend

Connect Remote Control

1. Ensure TV supports HDMI-CEC
2. Enable CEC in TV settings
3. Power on and connect remote
4. System automatically detects input

Switch to Plex

In the home screen, select "Watch Plex". The system will:

1. Exit fullscreen kiosk
2. Launch Plex media center
3. Return to kiosk when Plex closes

Troubleshooting

Services Won't Start

# Check Docker status
docker-compose ps

# View service logs
./scripts/logs.sh all

# Rebuild from scratch
./scripts/rebuild.sh

Frontend Not Loading

• Check API URL: VITE_API_URL in .env
• Verify Directus is running: http://localhost:8055
• Clear browser cache
• Check frontend logs: ./scripts/logs.sh frontend

Control Service Not Connecting

• Check WebSocket URL: VITE_WS_URL in .env
• Verify service is running: curl http://localhost:3001/health
• Check firewall rules
• Review service logs: ./scripts/logs.sh control

HDMI-CEC Not Working

# Test if cec-client is installed
which cec-client

# If not installed on Raspberry Pi
sudo apt-get install libcec-dev

# Test CEC connection
echo "as" | cec-client -s

Database Issues

# Restart database
docker-compose restart postgres

# Check database logs
./scripts/logs.sh db

# Backup and restore
docker-compose exec postgres pg_dump -U directus directus > backup.sql

File Structure

Hotel_Pi/
├── frontend/           # SvelteKit kiosk UI
├── control-service/    # Node.js WebSocket + CEC
├── directus/          # CMS configuration
├── scripts/           # Deployment & utility scripts
├── docker-compose.yml # Main orchestration
└── README.md          # Project documentation

Production Checklist

• Change all default passwords in .env
• Set SECRET and AUTH_SECRET to random values
• Configure CORS_ORIGIN for your domain
• Set up HTTPS (if exposing to internet)
• Configure automatic backups
• Set up log rotation
• Test HDMI-CEC on target TV
• Verify idle timeout settings
• Load test with sample data
• Prepare CMS content before deployment

Support & Documentation

• Frontend Guide: See frontend/README.md
• Control Service: See control-service/README.md
• CMS Setup: See directus/README.md
• Architecture: See main README.md

Next Steps

1. Add Content: Populate Directus with restaurants and attractions
2. Customize UI: Edit frontend components in frontend/src/components/
3. Configure Plex: Set up Plex media server and HTPC app
4. Test Workflow: Navigate through all screens
5. Deploy: Follow Raspberry Pi deployment steps above