This guide covers setting up a new Harvester installation for a franchise.

Prerequisites

• Raspberry Pi (3B+ or newer) with Ubuntu
• RP850A thermal printer with USB connection
• Gmail account for order forwarding
• Google Cloud project with OAuth credentials
• AWS account (SES, Lambda, DynamoDB)
• Railway account for cloud service hosting

Cloud Service Setup

1. Deploy to Railway

The cloud service deploys automatically from the main branch:

1. Connect your GitHub repository to Railway
2. Set the root directory to cloud-service/
3. Configure environment variables (see below)
4. Railway auto-deploys on push to main

2. Environment Variables

Configure these in the Railway dashboard:

• AWS_ACCESS_KEY_ID — AWS credentials for SES and DynamoDB
• AWS_SECRET_ACCESS_KEY — AWS secret key
• AWS_REGION — us-east-1
• EDGE_AGENT_SECRET — Shared secret for edge agent authentication
• GOOGLE_CLIENT_ID — Google OAuth client ID
• GOOGLE_CLIENT_SECRET — Google OAuth client secret
• JWT_SECRET — Strong random key for JWT signing
• DASHBOARD_BASE_URL — Your Railway deployment URL

3. Google OAuth Configuration

1. Create a project in Google Cloud Console
2. Enable the Gmail API and Google Calendar API
3. Configure the OAuth consent screen
4. Create OAuth 2.0 credentials (Web application type)
5. Add authorized redirect URIs pointing to your Railway URL

Edge Agent Setup

1. Install on Raspberry Pi

# Clone the repository
git clone <repo-url> /home/ubuntu/cmy-edge-agent

# Create virtual environment
cd /home/ubuntu/cmy-edge-agent
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configure Environment

Create /home/ubuntu/cmy-edge-agent/.env:

CLOUD_URL=https://your-railway-url.up.railway.app
EDGE_AGENT_SECRET=your-shared-secret
FRANCHISE_IDS=your_franchise_id
PRINTER_VENDOR=0x0fe6
PRINTER_PRODUCT=0x811e

3. Install as System Service

sudo cp cmy-edge-agent.service /etc/systemd/system/
sudo systemctl enable cmy-edge-agent
sudo systemctl start cmy-edge-agent

4. Verify Connection

Check that the edge agent connects to the cloud service:

sudo systemctl status cmy-edge-agent
tail -20 /home/ubuntu/cmy-edge-agent/edge_agent.log

Email Forwarding Setup

1. Configure AWS SES

1. Verify the franchise email domain in SES
2. Create a receipt rule for the franchise email address
3. Point the rule to the SNS topic that triggers Lambda

2. Configure Gmail Forwarding

1. Log into the franchise Gmail account
2. Go to Settings → Forwarding and POP/IMAP
3. Add forwarding address: franchise_id@orders.cb4.click
4. Confirm the forwarding via the confirmation link in Lambda logs
5. Enable forwarding for all incoming mail (or use a filter)

Verification Checklist

After setup, verify each component:

• Cloud service responds at /health endpoint
• Google OAuth login works on the dashboard
• Edge agent shows as connected in dashboard
• Test print succeeds via /test/print endpoint
• Email forwarding delivers to the system
• Order appears in dashboard after email receipt