This guide covers routine operations, monitoring, and troubleshooting for a running Harvester installation.

Daily Operations

Monitoring System Health

Check the system health endpoint:

GET https://receiptprinter-production.up.railway.app/health

The dashboard shows:

• Edge agent connectivity and last heartbeat
• Printer status (ready, offline, paper low/out)
• Pending print queue size
• Recent order activity

Checking Print Status

Orders flow through these states:

1. Received — Email parsed and order created
2. Queued — Print command enqueued for edge agent
3. Printed — Edge agent confirmed print completion
4. Error — Print failed (check edge agent logs)

Common Issues

Printer Shows Offline

1. Check physical printer power and USB connection
2. Verify edge agent service is running:

   sudo systemctl status cmy-edge-agent

3. Check edge agent logs for USB errors:

   tail -50 /home/ubuntu/cmy-edge-agent/edge_agent.log

4. Restart the service if needed:

   sudo systemctl restart cmy-edge-agent

Orders Not Printing

1. Verify the order appears in the dashboard
2. Check if the edge agent is connected (dashboard shows last heartbeat)
3. Check Railway logs for command enqueue confirmation
4. Check edge agent logs for command receipt
5. If commands are queued but not received, restart the edge agent

Edge Agent Won’t Connect

1. Verify internet connectivity on the Pi
2. Check that CLOUD_URL and EDGE_AGENT_SECRET in .env are correct
3. Check for “Resource busy” USB errors (restart service)
4. Verify the Railway service is running

Paper Out / Paper Low

The system detects paper status via ESC/POS status commands:

• Paper Low — Replace paper roll soon
• Paper Out — Printing halted until paper is loaded

After loading paper, the system automatically resumes printing queued orders.

Deployment

Cloud Service Updates

Push to the main branch triggers automatic Railway deployment:

git add .
git commit -m "Update description"
git push origin main

Railway deploys in 1-2 minutes. Monitor logs after deployment.

Edge Agent Updates

Edge agent updates deploy via GitHub Actions when files in edge-agent/ change:

1. Push changes to main branch
2. GitHub Actions SSHs to the Pi and deploys updated files
3. Service restarts automatically
4. Verify with a test print

Manual Edge Agent Update (Fallback)

If GitHub Actions deployment fails:

scp edge-agent/src/edge_agent.py ubuntu@<pi-ip>:/home/ubuntu/cmy-edge-agent/src/
ssh ubuntu@<pi-ip> "sudo systemctl restart cmy-edge-agent"

Monitoring

Railway Logs

View recent cloud service logs:

railway logs --tail 50

Key log patterns to watch:

• [INFO] Print command sent to <franchise> — Command enqueued
• [INFO] Print completed: Order <id> — Successful print
• [WARN] No connected edge agent — Edge agent offline
• [ERROR] — Any error requires investigation

Edge Agent Logs

tail -100 /home/ubuntu/cmy-edge-agent/edge_agent.log

Key patterns:

• 📬 Received 1 command(s) — Command received from cloud
• ✅ Print successful — Physical print completed
• ⚠️ Polling failed: HTTP 502 — Temporary Railway timeout (auto-recovers)

Backup and Recovery

Order Data

Order data is stored in AWS DynamoDB with automatic backups. Point-in-time recovery is available for the last 35 days.

Edge Agent Recovery

If the Pi needs to be rebuilt:

1. Flash Ubuntu to SD card
2. Follow the Edge Agent Setup guide
3. Restore .env configuration
4. The edge agent will reconnect and resume printing queued orders

Cloud Service Recovery

Railway maintains deployment history. To rollback:

railway rollback