================================================================================
RBIO-Mesh-Kit: Raspberry Pi 5 Setup Guide
================================================================================
Version: 1.0
Target OS: Raspberry Pi OS Lite (64-bit)
Author: RBIO Project

This guide will walk you through setting up your Raspberry Pi 5 to act as the
central "Brain" of your Role-Based Identity Ownership (RBIO) mesh.

--------------------------------------------------------------------------------
TABLE OF CONTENTS
--------------------------------------------------------------------------------
1. Prerequisites
2. Installing Raspberry Pi OS Lite
3. Initial Configuration (SSH & Network)
4. Installing Docker and Docker Compose
5. Generating SSL/TLS Certificates (CRITICAL STEP)
6. Deploying the RBIO Stack
7. Verifying the System
8. Troubleshooting

--------------------------------------------------------------------------------
1. PREREQUISITES
--------------------------------------------------------------------------------
- Raspberry Pi 5 (4GB or 8GB RAM recommended)
- MicroSD Card (Class 10, A2) or USB SSD
- Power Supply (USB-C, 5V/5A)
- Keyboard/Monitor (for initial setup) or SSH access from another computer
- Internet connection (for initial updates)

--------------------------------------------------------------------------------
2. INSTALLING RASPBERRY PI OS LITE
--------------------------------------------------------------------------------
1. Download "Raspberry Pi OS Lite (64-bit)" from:
   https://www.raspberrypi.com/software/operating-systems/

2. Use "Raspberry Pi Imager" to flash the OS to your SD card or SSD.
   - Select "Raspberry Pi OS Lite (64-bit)".
   - Select your storage device.
   - Click "Settings" (gear icon) BEFORE writing:
     * Set Hostname: "rbio-pi"
     * Enable SSH: Yes (use password authentication)
     * Set Username/Password: (Choose a strong password)
     * Configure Wireless LAN: (Optional, if using Wi-Fi)
   - Write the image.

3. Insert the card/SSD into the Pi and power it on.
4. Wait 2-3 minutes for the first boot.

--------------------------------------------------------------------------------
3. INITIAL CONFIGURATION (SSH & NETWORK)
--------------------------------------------------------------------------------
1. Find your Pi's IP address:
   - Check your router's admin page, or use:
     ping rbio-pi.local
   - Note the IP address (e.g., 192.168.1.50).

2. SSH into the Pi from your computer:
   ssh username@192.168.1.50
   (Replace "username" with the one you set in the Imager).

3. Update the system:
   sudo apt update && sudo apt full-upgrade -y

4. (Optional) Change your password:
   passwd

5. Reboot:
   sudo reboot

--------------------------------------------------------------------------------
4. INSTALLING DOCKER AND DOCKER COMPOSE
--------------------------------------------------------------------------------
The RBIO stack runs in Docker containers. Run these commands in your SSH session:

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

2. Add your user to the Docker group (so you don't need 'sudo' for docker commands):
   sudo usermod -aG docker $USER
   newgrp docker

3. Install Docker Compose Plugin:
   sudo apt install docker-compose-plugin -y

4. Verify installation:
   docker --version
   docker compose version

--------------------------------------------------------------------------------
5. GENERATING SSL/TLS CERTIFICATES (CRITICAL STEP)
--------------------------------------------------------------------------------
The MQTT broker requires SSL/TLS certificates to encrypt communication between
the Pi and the phones. The ZIP kit includes a script to generate these.

1. Navigate to the config directory:
   cd ~/rbio-mesh/config/mqtt-certificates

2. Run the certificate generation script:
   bash generate_certs.sh

   This script will:
   - Create a self-signed Certificate Authority (CA).
   - Generate a Server Certificate and Private Key for the Pi.
   - Place them in the current directory (ca.crt, server.crt, server.key).

   NOTE: If the script fails, you can generate them manually with OpenSSL:
   openssl genrsa -out ca.key 4096
   openssl req -new -x509 -days 3650 -key ca.key -out ca.crt
   openssl genrsa -out server.key 2048
   openssl req -new -key server.key -out server.csr
   openssl x509 -req -days 3650 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

3. Verify the files exist:
   ls -l
   You should see: ca.crt, server.crt, server.key

4. Set permissions (optional but recommended):
   chmod 600 server.key
   chmod 644 server.crt ca.crt

--------------------------------------------------------------------------------
6. DEPLOYING THE RBIO STACK
--------------------------------------------------------------------------------
1. Navigate to the project root:
   cd ~/rbio-mesh

2. (Optional) Edit configuration files:
   nano config/thresholds.json
   (Adjust time/distance triggers as needed)

   nano config/roles.json
   (Add or remove role names)

3. Start the stack:
   docker compose up -d

   This will start three containers:
   - rbio-mqtt (Mosquitto Broker)
   - rbio-db (SQLite Database)
   - rbio-server (Flask App + Entropy Engine)

4. Check the status:
   docker compose ps
   All three should show "Up".

5. View logs (if troubleshooting):
   docker compose logs -f

--------------------------------------------------------------------------------
7. VERIFYING THE SYSTEM
--------------------------------------------------------------------------------
1. Test the MQTT Broker:
   Install an MQTT client on your computer (e.g., MQTTX or mosquitto_pub).
   Connect to:
   Host: 192.168.1.50 (your Pi's IP)
   Port: 1883 (or 8883 if using TLS)
   Username/Password: (None by default, or set in mosquitto.conf)
   
   Subscribe to topic: rbio/commands
   Publish a test message to: rbio/heartbeat
   {"device_id": "test", "timestamp": "now"}

2. Test the Web Server:
   Open a browser on your computer and go to:
   http://192.168.1.50:5000
   You should see the "RBIO Provisioning Server" welcome page.

3. Check Database:
   docker compose exec rbio-db sqlite3 /data/roles.db ".tables"
   You should see: roles, swap_history, config

--------------------------------------------------------------------------------
8. TROUBLESHOOTING
--------------------------------------------------------------------------------
Problem: "Permission denied" when running docker commands.
Solution: Run 'newgrp docker' again or reboot.

Problem: MQTT connection fails with "Certificate verify failed".
Solution: Ensure you ran 'generate_certs.sh' and the files are in the correct folder.
Check that the phones have the 'ca.crt' file installed in their trust store.

Problem: Container won't start.
Solution: Check logs: docker compose logs rbio-server
Common issue: Port 5000 or 1883 already in use. Change ports in docker-compose.yml.

Problem: Can't reach the Pi from phones.
Solution: Ensure phones are on the SAME Wi-Fi network as the Pi.
Check firewall: sudo ufw status (should allow 1883 and 5000).

================================================================================
END OF PI SETUP GUIDE
================================================================================