Reverse Proxy & Subdomain Routing¶

This document defines the reverse proxy architecture using Traefik for subdomain-based routing of the Chaverim ALPR Platform services.

Document Status: Proposed Last Updated: 2025-12-30

Table of Contents¶

Overview
Subdomain Structure
Architecture
Routing Rules
SSL/TLS Configuration
Security Considerations
Deployment

1. Overview¶

The platform uses Traefik as a reverse proxy to route traffic to different services based on subdomain. This provides:

Service isolation - Each service has its own subdomain and routing rules
Independent scaling - Services can scale independently without affecting routing
Security boundaries - Different authentication and rate limiting per service
Automatic SSL - Let's Encrypt certificates with automatic renewal

Domain: *.chvrm.flowcmd.io

2. Subdomain Structure¶

Subdomain	Service	Purpose	Access
`app.chvrm.flowcmd.io`	Central Web App	User interface, search, alerts, admin	Authenticated users
`ingest.chvrm.flowcmd.io`	Ingest Service	Edge collector uploads, camera webhooks	API key authenticated
`docs.chvrm.flowcmd.io`	Documentation Site	Public architecture and feature docs	Public
`traefik.chvrm.flowcmd.io`	Traefik Dashboard	Monitoring and debugging	Admin only (internal)

Traffic Patterns¶

Subdomain	Expected Traffic	Characteristics
`app`	Low-medium	Interactive users, WebSocket connections
`ingest`	High	Burst traffic, batch uploads, 100+ detections/min
`docs`	Low	Static content, cacheable
`traefik`	Minimal	Admin access only, internal network

3. Architecture¶

                                    Internet
                                        │
                                        ▼
                              ┌─────────────────┐
                              │     Traefik     │
                              │  Reverse Proxy  │
                              │   (Port 443)    │
                              └────────┬────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
                    ▼                  ▼                  ▼
            ┌───────────────┐  ┌───────────────┐  ┌───────────────┐
            │  app.chvrm.*  │  │ ingest.chvrm.*│  │ docs.chvrm.*  │
            │               │  │               │  │               │
            │   Central     │  │    Ingest     │  │    MkDocs     │
            │   FastAPI     │  │   Service     │  │   Material    │
            │   + Frontend  │  │   (FastAPI)   │  │   (Static)    │
            └───────────────┘  └───────────────┘  └───────────────┘
                    │                  │
                    ▼                  ▼
            ┌───────────────┐  ┌───────────────┐
            │  PostgreSQL   │  │     MinIO     │
            │   + MinIO     │  │  (if needed)  │
            └───────────────┘  └───────────────┘

Container Topology¶

Container	Internal Port	Traefik Route
`central-app`	8000	`app.chvrm.flowcmd.io`
`ingest`	8001	`ingest.chvrm.flowcmd.io`
`docs`	8080	`docs.chvrm.flowcmd.io`
`traefik`	80, 443	Entry point
`postgres`	5432	Internal only
`minio`	9000	Internal only (presigned URLs via app)

4. Routing Rules¶

App Subdomain¶

Routes to central FastAPI application.

Path	Backend	Notes
`/*`	`central-app:8000`	All app traffic
`/ws/*`	`central-app:8000`	WebSocket upgrade for real-time

Middleware: - Rate limiting: 100 req/min per IP (authentication endpoints) - Headers: Security headers (CSP, HSTS, etc.)

Ingest Subdomain¶

Routes to ingest service for edge collector uploads and camera webhooks.

Path	Backend	Notes
`/api/v1/detections/*`	`ingest:8001`	Detection batch uploads
`/api/v1/heartbeat`	`ingest:8001`	Collector heartbeat
`/api/v1/ingest/*`	`ingest:8001`	Camera webhooks
`/health`	`ingest:8001`	Health check

Middleware: - No rate limiting - uses backpressure signaling (see Rate Limiting) - Large request body limit (10MB for batch uploads with images) - IP allowlist (optional, for collector IPs only)

Docs Subdomain¶

Routes to MkDocs Material static site.

Path	Backend	Notes
`/*`	`docs:8080`	All documentation

Middleware: - Caching headers (static content) - No authentication required

5. SSL/TLS Configuration¶

Certificate Management¶

Traefik handles SSL certificates automatically via Let's Encrypt ACME.

Setting	Value
ACME Provider	Let's Encrypt
Challenge Type	TLS-ALPN-01 (preferred) or HTTP-01
Certificate Storage	Docker volume (`traefik-certs`)
Renewal	Automatic (30 days before expiry)

TLS Settings¶

Setting	Value	Rationale
Minimum Version	TLS 1.2	Compatibility with older edge collectors
Preferred Version	TLS 1.3	Maximum security and performance
Cipher Suites	Modern (ECDHE, AES-GCM)	Forward secrecy, authenticated encryption
HSTS	Enabled, max-age=31536000	Force HTTPS for all future requests

Wildcard Certificate¶

A single wildcard certificate (*.chvrm.flowcmd.io) covers all subdomains.

Requirements: - DNS-01 challenge (required for wildcard) - DNS provider API access for automated validation

6. Security Considerations¶

Network Isolation¶

Service	External Access	Internal Access
Traefik	Yes (80, 443)	All containers
central-app	Via Traefik only	postgres, minio
ingest	Via Traefik only	central-app, minio
docs	Via Traefik only	None
postgres	No	central-app only
minio	No	central-app, ingest

Ingest Subdomain Hardening¶

The ingest subdomain handles edge collector traffic. Additional security measures:

API key validation - All requests require valid X-API-Key header
IP allowlisting (optional) - Restrict to known collector IPs
Request size limits - 10MB max for batch uploads
No browser access needed - Can disable CORS, cookies

Traefik Dashboard¶

The Traefik dashboard provides monitoring and debugging.

Setting	Value
Enabled	Yes (production)
Access	`traefik.chvrm.flowcmd.io` (internal only)
Authentication	Basic auth (admin credentials)
Exposure	Internal network only, not public

7. Deployment¶

DNS Configuration¶

Create the following DNS records (A or CNAME):

Record	Type	Value
`app.chvrm.flowcmd.io`	A	`<server-ip>`
`ingest.chvrm.flowcmd.io`	A	`<server-ip>`
`docs.chvrm.flowcmd.io`	A	`<server-ip>`
`traefik.chvrm.flowcmd.io`	A	`<server-ip>`

Or use a wildcard:

Record	Type	Value
`*.chvrm.flowcmd.io`	A	`<server-ip>`

Docker Compose Integration¶

Traefik runs as part of the central server Docker Compose stack:

Service	Role
`traefik`	Reverse proxy, SSL termination
`central-app`	Main application
`ingest`	Ingest service (central mode)
`docs`	Documentation site
`postgres`	Database
`minio`	Object storage

Services declare their routing via Docker labels, allowing Traefik to auto-discover routes.

Health Checks¶

Endpoint	Purpose
`app.chvrm.flowcmd.io/health`	Central app health
`ingest.chvrm.flowcmd.io/health`	Ingest service health
`docs.chvrm.flowcmd.io/`	Docs site availability

Architecture: Ingest Service - Unified ingest service
Architecture: Documentation Site - Public docs site
PRP: Global Patterns - Security patterns

Document Maintainer: Architecture Team Review Cycle: Update when infrastructure changes