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
```bash
cd /path/to/Hotel_Pi
cp .env.example .env
```

### 3. Start Services
```bash
docker-compose up -d
```

Wait for all services to be healthy:
```bash
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

```bash
cd frontend
npm install
npm run dev
```

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

### Run Control Service Locally

```bash
cd control-service
npm install
npm run dev
```

WebSocket available at ws://localhost:3001

### Docker Development Mode

Use the dev override file:
```bash
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](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
```bash
# 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:
```bash
# .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

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

```bash
# 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`:
```bash
WELCOME_NAME="Welcome, Guest"
IDLE_TIMEOUT_MINUTES=5
```

Then restart frontend:
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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](frontend/README.md)
- **Control Service:** See [control-service/README.md](control-service/README.md)
- **CMS Setup:** See [directus/README.md](directus/README.md)
- **Architecture:** See main [README.md](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