Deployment¶

Deployment Models Overview¶

JunctionRelay supports multiple deployment modes:

🔒 Fully Offline Local Only
☁️ Cloud-Connected Hybrid
⚡ Zero Trust Secure Proxy Model
🐳 Fully Dockerized Portable Architecture

All deployment modes are fully self-contained with no mandatory cloud reliance unless cloud features are explicitly desired.

Full Component Deployment Matrix¶

Component	Description	Deployment Type	Hosting Options
JunctionRelay_Server_Local	Local orchestration backend	Docker or native binary	Self-hosted LAN server (Windows/Linux/Raspberry Pi/Unraid/Portainer)
JunctionRelay_Server_Frontend	Local management web UI	Static SPA	CDN, Render Static Site, Docker NGINX container
JunctionRelay_Cloud	Cloud backend API	Docker	Render Web Service (primary), Kubernetes, or custom VPS
JunctionRelay_Worker	Cloud background worker	Docker	Render Background Worker (primary)
JunctionRelay_Dashboard	Cloud user dashboard	Static SPA	Render Static Site or any CDN
ESP32 Devices	Embedded firmware clients	Arduino firmware	Local WiFi or Ethernet LAN

Local-Only Deployment¶

Supports completely isolated air-gapped deployments
No cloud APIs or credentials required
Local-only features fully available:
Junction orchestration
Collectors integration (HomeAssistant, LibreHardwareMonitor, HTTP, MQTT)
WebSocket device streaming (LAN-only)
OTA firmware management (manually loaded firmware files)
Full device, junction, and sensor configuration

Typical Local Stack (Docker Compose):

junctionrelay_server_local
junctionrelay_server_frontend
(optional: local MQTT broker)
SQLite database (embedded)

Cloud-Connected Hybrid Deployment¶

Enables cloud-licensed features:
Device remote registration and approvals
Cloud billing integration via Stripe
Cloud licensing enforcement
OTA firmware releases managed via GitHub integration
Fully Zero Trust proxy architecture ensures no inbound cloud access required

Typical Cloud Stack (Render Services):

junctionrelay_cloud (Web Service)
junctionrelay_worker (Background Worker)
junctionrelay_dashboard (Static Site)
Postgres database (Render Postgres)
Redis Streams (Upstash Redis)

Local Stack (Self-Hosted):

junctionrelay_server_local
junctionrelay_server_frontend

Required Environment Variables¶

Local Backend (`junctionrelay_server_local`)¶

Variable	Purpose
`LOCAL_ENCRYPTION_KEY`	(optional) Encryption for DB secrets
`DATABASE_PASSWORD`	(optional) SQLite DB password

Cloud Backend (`junctionrelay_cloud`)¶

Variable	Purpose
`CLERK_SECRET_KEY`	Clerk OAuth service key
`STRIPE_SECRET_KEY`	Stripe subscription billing key
`STRIPE_WEBHOOK_SECRET`	Stripe webhook verification
`POSTGRES_CONNECTION_STRING`	Render Postgres DB connection
`REDIS_CONNECTION_URL`	Upstash Redis stream queue

Cloud Worker (`junctionrelay_worker`)¶

Variable	Purpose
`POSTGRES_CONNECTION_STRING`	Render Postgres DB connection
`REDIS_CONNECTION_URL`	Upstash Redis stream queue

Frontend Config (Static Builds)¶

Frontend typically expects /api relative path
Optionally controlled via REACT_APP_API_URL during frontend build phase
Supports absolute or relative API endpoint mappings for complex deployments

Docker Deployment Example (Local Only)¶

docker network create junctionrelay

docker run -d \
  --name jr_backend \
  --network junctionrelay \
  -v /data/junctionrelay:/app/data \
  -e DATABASE_PASSWORD=xxx \
  -e LOCAL_ENCRYPTION_KEY=xxx \
  catapultcase/junctionrelay_server_local:latest

docker run -d \
  --name jr_frontend \
  --network junctionrelay \
  -p 8080:80 \
  catapultcase/junctionrelay_server_frontend:latest

Frontend served on http://localhost:8080
Backend available internally to frontend via /api proxy path
WebSocket available via LAN at /ws/device

Render Deployment Example (Cloud Backend)¶

Cloud Backend (junctionrelay_cloud)¶

Type: Web Service (Docker)
Region: Oregon or preferred region
Build Command: docker build -t cloud .
Start Command: dotnet JunctionRelay_Cloud.dll

Cloud Worker (junctionrelay_worker)¶

Type: Background Worker (Docker)
Build Command: docker build -t worker .
Start Command: dotnet JunctionRelay_Worker.dll

Cloud Dashboard (junctionrelay_dashboard)¶

Type: Static Site
Build Command: npm run build
Output Directory: build/

Render Postgres¶

Starter or Standard Tier depending on scale

Upstash Redis Streams¶

Free or low-tier plan initially sufficient

OTA Firmware Deployment Notes¶

Cloud backend monitors GitHub release repositories
Releases populated via GitHub public tags
OTA firmware release cache refreshed via admin dashboard or backend API
Local-only installations may manually load OTA files if desired

Multi-Gateway Support¶

Multiple junctionrelay_server_local instances may operate on distributed physical nodes
Supports horizontal expansion by assigning distinct brokers (MQTT, COM, HTTP)
Gateway role coordination managed entirely locally without central coordinator required
Devices automatically discover local backend via LAN broadcast WebSocket advertisements

Portainer / Unraid Compatibility¶

Fully compatible with Unraid Docker manager
Fully compatible with Portainer stack deployments
Compose files easily adapted to these orchestration systems

Scalability Notes¶

Fully stateless frontend (infinitely horizontally scalable)
Stateless cloud worker (safe for scaling workers independently)
Cloud backend horizontally scalable (subject to Render worker pool limits)
Local backend remains single-node per physical deployment (unless multiple gateways are deployed)
Redis Streams allow high-throughput asynchronous task buffering
Postgres safely handles linear growth of cloud userbase

High Availability Future Model¶

Redis Streams may be horizontally partitioned for very high throughput workloads
Cloud backend can adopt HA cluster model via container orchestrators (Kubernetes, Nomad)
Local gateway nodes may support soft failover / distributed leader election models for future designs

Monitoring & Health Checks¶

Component	Health Endpoint
Local Backend	`/health`
Cloud Backend	`/health`
Worker	Internal Redis metrics (future dashboard planned)
Frontend	Fully static (availability tied to CDN uptime)
ESP32 Devices	Live heartbeats visible via frontend UI

Upgrade Strategy¶

Frontend upgrades deployed via static site redeploy (safe rolling upgrade)
Backend upgrades deployed via container tag upgrades (no DB migrations unless version release notes specify)
OTA firmware upgraded via secure cloud releases
Fully backwards compatible API contracts unless major version breaking change noted

Disaster Recovery Model¶

Component	Recovery Strategy
Local Backend	Restore SQLite file backup
Cloud Backend	Render backup snapshot restore
Cloud Worker	Redeploy container (stateless)
Postgres	Automated backups via Render (paid plans)
Redis Streams	Upstash data persistence plans
Devices	Automatic recovery post-reflash; tokens persisted locally

Summary¶

JunctionRelay supports extremely flexible deployment topologies, allowing everything from small single-node Raspberry Pi installations to multi-tenant cloud SaaS models with distributed gateways and secure cloud licensing enforcement. The fully Dockerized architecture allows simple adoption across self-hosted hobby deployments, enterprise-class on-prem installations, and highly scalable clou

Deployment¶

Deployment Models Overview¶

Full Component Deployment Matrix¶

Local-Only Deployment¶

Cloud-Connected Hybrid Deployment¶

Required Environment Variables¶

Local Backend (junctionrelay_server_local)¶

Cloud Backend (junctionrelay_cloud)¶

Cloud Worker (junctionrelay_worker)¶

Frontend Config (Static Builds)¶

Docker Deployment Example (Local Only)¶

Render Deployment Example (Cloud Backend)¶

Cloud Backend (junctionrelay_cloud)¶

Cloud Worker (junctionrelay_worker)¶

Cloud Dashboard (junctionrelay_dashboard)¶

Render Postgres¶

Upstash Redis Streams¶

OTA Firmware Deployment Notes¶

Multi-Gateway Support¶

Portainer / Unraid Compatibility¶

Scalability Notes¶

High Availability Future Model¶

Monitoring & Health Checks¶

Upgrade Strategy¶

Disaster Recovery Model¶

Summary¶

Local Backend (`junctionrelay_server_local`)¶

Cloud Backend (`junctionrelay_cloud`)¶

Cloud Worker (`junctionrelay_worker`)¶