Open-Source & Infrastructure

Resources for developers and contributors to the Chicago Mesh network.

🏗️ Infrastructure

Production Environment

• Instance: AWS EC2 t3.small (us-east-2)
• Services:
  • corescope — CoreScope packet analyzer
  • mosquitto — Standalone Mosquitto MQTT broker (port 1883)
  • meshcore-mqtt-broker — WebSocket MQTT broker with JWT auth
  • meshcore-health-check — Mesh Health Check app
  • caddy — Reverse proxy / TLS termination
• URLs:
  • scope.chicagooffline.com — Network Scope
  • health.chicagooffline.com — Health Check
  • mqtt.chicagooffline.com:1883 — Plain TCP MQTT
  • wss://wsmqtt.chicagooffline.com/mqtt — WebSocket MQTT (JWT auth)
  • tiles.chicagooffline.com — Map Tile Server

Development Environment

• Instance: AWS EC2 t3.small (us-east-2)
• Services:
  • corescope-dev — CoreScope dev instance
  • mosquitto — Standalone Mosquitto MQTT broker
  • meshcore-mqtt-broker — WebSocket MQTT broker with JWT auth
  • meshcore-health-check-dev — Mesh Health Check dev instance
  • meshmap-live — Live MQTT node map (yellowcooln/meshcore-mqtt-live-map)
  • caddy — Reverse proxy / TLS termination
• URLs:
  • dev-scope.chicagooffline.com — Dev Network Scope
  • dev-health.chicagooffline.com — Dev Health Check
  • dev-landing.chicagooffline.com — Dev Landing Page
  • dev-livemap.chicagooffline.com — Dev Live Map
  • dev-keygen.chicagooffline.com — Dev Key Generator
  • wss://wsmqtt-dev.chicagooffline.com/mqtt — WebSocket MQTT (JWT auth)

📦 GitHub Repositories

Main Deployment Repo

• Repo: github.com/emuehlstein/chimesh-mqtt
• Branches:
  • main — Development deployments (safe to push freely)
  • prod — Production deployments (promote from main)
• CI/CD: GitHub Actions auto-deploys on push to main (dev) or prod (production)

CoreScope Source (Fork)

• Upstream: github.com/meshcore-dev/CoreScope
• Fork: github.com/emuehlstein/CoreScope-chicagooffline (branch: deploy/chicagooffline)
• Build Mode: CORESCOPE_IMAGE_MODE=fork in deploy.sh

MeshCore Chicagoland Observer Firmware

• Fork: github.com/emuehlstein/MeshCore
• Branch: chioff-flex (based on agessaman's mqtt-bridge-implementation-flex)
• Release: Latest release
• Features: Multi-slot MQTT (up to 6 brokers), preset system, PSRAM-aware memory management, embedded CA bundle, radio watchdog
• Boards: Heltec V3, Heltec V4, Station G2, T-Beam SX1262, T-Beam S3 Supreme, LilyGo T3S3
• Default MQTT presets:
  • chimesh — chimesh.org WSS broker
  • chioff — chicagooffline.com WSS broker
  • analyzer-us — LetsMesh US (G2 only, or user-configured)
• Chicagoland radio defaults: 910.525 MHz / BW 62.5 / SF7 / CR5, 3-byte path hash, moderate loop detect

Mesh Health Check

• Upstream: github.com/yellowcooln/meshcore-health-check
• Fork: github.com/emuehlstein/meshcore-health-check (Chicago Mesh color system reskin)
• Live: health.chicagooffline.com

🚀 Deployment

Automated (GitHub Actions)

# Push to main → deploys to dev only
git push origin main

# Promote dev → production
git checkout prod && git merge main && git push && git checkout main

# Manual workflow dispatch
gh workflow run deploy.yml -f environment=dev
gh workflow run deploy.yml -f environment=production
gh workflow run deploy.yml -f environment=dev -f reset_db=true

Manual Deployment

# SSH into EC2
ssh ubuntu@<ec2-ip>  # prod or dev IP

# Pull latest changes
cd ~/chimesh-mqtt
git pull origin main  # or dev

# Run deploy script
ENVIRONMENT=production bash deploy.sh  # or ENVIRONMENT=dev

🔧 Development Workflow

1. Make changes to CoreScope fork or config files
2. Commit and push to main branch
3. GitHub Actions auto-deploys to dev (dev-scope.chicagooffline.com)
4. Test changes in browser
5. Promote to prod: git checkout prod && git merge main && git push && git checkout main
6. GitHub Actions auto-deploys to production (scope.chicagooffline.com)

📊 Monitoring

Logs (Production)

ssh ubuntu@<prod-ip>

# CoreScope logs
docker logs -f corescope

# MQTT broker logs
docker logs -f mosquitto

# Caddy (reverse proxy) logs
docker logs -f caddy

# Health Check logs
docker logs -f meshcore-health-check

Logs (Development)

ssh ubuntu@<dev-ip>

# CoreScope logs
docker logs -f corescope-dev

# Mosquitto logs
docker logs -f mosquitto

# WS MQTT broker logs
docker logs -f meshcore-mqtt-broker

# Health Check logs
docker logs -f meshcore-health-check-dev

# Caddy logs
docker logs -f caddy

📡 Connecting Observer Nodes

Want to add your node's packet data to the Chicago Offline live map and scope?

See the observer setup guide →

Covers the one-line installer, plain TCP, WebSocket+JWT, and per-node-type config.

💡 Contributing

Interested in contributing to the Chicago Mesh network infrastructure?

• Join the Chicagoland Mesh community
• Open issues or PRs on the chimesh-mqtt repo
• Deploy your own observer node and publish to the MQTT broker
• Help improve CoreScope or the Health Check app