Backend, sync, infra, docs: ETag, API versioning, k8s, web scaffold, Android 16, domain stubs

- Backend: ShallowEtagHeaderFilter for /api/v1/*, API-VERSIONING.md, README (tenant, CORS, Flyway, ETag) - k8s: backend-deployment.yaml (Deployment, Service, Secret/ConfigMap) - Web: scaffold with directory pull, 304 handling, touch-friendly UI - Android 16: ANDROID-16-TARGET.md; BuildConfig STUN/signaling, SMOAApplication configures InfrastructureManager - Domain: CertificateManager revocation stub, ReportService signReports, ZeroTrust/ThreatDetection minimal docs - TODO.md and IMPLEMENTATION_STATUS.md updated; communications README for endpoint config Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 20:37:01 -08:00
parent 97f75e144f
commit 5a8c26cf5d
101 changed files with 4923 additions and 103 deletions
--- a/docs/infrastructure/PROXMOX-VE-TEMPLATE-REQUIREMENTS.md
+++ b/docs/infrastructure/PROXMOX-VE-TEMPLATE-REQUIREMENTS.md
@@ -0,0 +1,167 @@
+# Proxmox VE template – hardware requirements for SMOA backend and supporting infra
+
+This document lists **hardware requirements** for building a **Proxmox VE template** used to run the SMOA backend and supporting infrastructure (database, optional reverse proxy, optional TURN/signaling).
+
+---
+
+## Required target (mandatory minimum)
+
+The **minimum viable target** for a single Proxmox VE template running the SMOA backend is:
+
+| Aspect | Required minimum |
+|--------|-------------------|
+| **Backend VM** | 2 vCPU, 1 GiB RAM, 8 GiB disk, 1 Gbps network |
+| **OS** | Linux (e.g. Debian 12 or Ubuntu 22.04 LTS) |
+| **Java** | OpenJDK 17 (Eclipse Temurin or equivalent) |
+| **Backend** | `smoa-backend` JAR on port 8080; H2 file DB or PostgreSQL |
+| **Data** | Persistent storage for `./data/smoa` (H2) or PostgreSQL data directory |
+| **Proxmox host** | 4 physical cores, 8 GiB RAM, 128 GiB SSD, 1 Gbps NIC |
+
+Below this, the backend may run but is not supported for production (no headroom for spikes, logs, or audit growth). All other dimensions (RAM, disk, vCPU, separate DB/proxy/TURN) are **scaling aspects** described in the next section.
+
+---
+
+## 1. Backend service (smoa-backend)
+
+| Resource | Minimum (dev/small) | Recommended (production) | Notes |
+|----------|----------------------|---------------------------|--------|
+| **vCPU** | 2 | 4 | Spring Boot + JPA; sync and pull endpoints can spike briefly. |
+| **RAM** | 1 GiB | 2–4 GiB | JVM heap ~512 MiB–1 GiB; leave headroom for OS and buffers. |
+| **Disk** | 8 GiB | 20–40 GiB | OS + JAR + H2 data (or PostgreSQL data dir if DB on same VM). Logs and audit table growth. |
+| **Network** | 1 Gbps (shared) | 1 Gbps | API traffic; rate limit 120 req/min per client by default. |
+
+- **Stack:** OpenJDK 17 (Eclipse Temurin), Spring Boot 3, Kotlin; H2 (file) or PostgreSQL.
+- **Ports:** 8080 (HTTP); optionally 8443 if TLS is terminated on the VM.
+- **Storage:** Persistent volume for `./data/smoa` (H2) or PostgreSQL data directory; consider separate disk for logs/audit.
+
+---
+
+## 2. Supporting infrastructure (same or separate VMs)
+
+### 2.1 Database (if not H2 on backend VM)
+
+When moving off H2 to **PostgreSQL** (recommended for production):
+
+| Resource | Minimum | Recommended |
+|----------|---------|-------------|
+| **vCPU** | 2 | 2–4 |
+| **RAM** | 1 GiB | 2–4 GiB |
+| **Disk** | 20 GiB | 50–100 GiB (SSD preferred) |
+| **Network** | 1 Gbps | 1 Gbps |
+
+- Can run on the **same Proxmox VM** as the backend (small deployments) or a **dedicated VM** (better isolation and scaling).
+
+### 2.2 Reverse proxy (optional)
+
+If you run **Nginx**, **Traefik**, or **Caddy** in front of the backend (TLS, load balancing, rate limiting):
+
+| Resource | Minimum | Notes |
+|----------|---------|--------|
+| **vCPU** | 1 | Light. |
+| **RAM** | 512 MiB | |
+| **Disk** | 4 GiB | Config + certs + logs. |
+
+- Can share a VM with the backend (e.g. Nginx in same template, backend as systemd service) or run as a separate small VM.
+
+### 2.3 TURN / signaling (optional)
+
+If you host **TURN** and/or **signaling** for WebRTC (meetings) instead of using external services:
+
+| Resource | Minimum | Recommended |
+|----------|---------|-------------|
+| **vCPU** | 2 | 4 |
+| **RAM** | 1 GiB | 2 GiB |
+| **Disk** | 10 GiB | 20 GiB |
+| **Network** | 1 Gbps | 1 Gbps+, low latency |
+
+- Media traffic can be CPU- and bandwidth-heavy; size for peak concurrent sessions.
+
+---
+
+## 3. Combined “all-in-one” template (single VM)
+
+A single Proxmox VE template that runs backend + PostgreSQL + optional Nginx on one VM:
+
+| Resource | Minimum | Recommended (production) |
+|----------|---------|---------------------------|
+| **vCPU** | 4 | 6–8 |
+| **RAM** | 4 GiB | 8 GiB |
+| **Disk** | 40 GiB | 80–120 GiB (SSD) |
+| **Network** | 1 Gbps | 1 Gbps |
+
+- **Layout:**  
+  - OS (e.g. Debian 12 / Ubuntu 22.04 LTS), Docker or systemd.  
+  - Backend JAR (or container), listening on 8080.  
+  - PostgreSQL (if used) and optional Nginx on same host.  
+  - Persistent volumes for DB data, backend H2 (if kept), and logs.
+
+---
+
+## 4. Proxmox VE host (physical) recommendations
+
+To run one or more VMs built from the template:
+
+| Resource | Small (dev / few users) | Production (dozens of devices) |
+|----------|---------------------------|-------------------------------|
+| **CPU** | 4 cores | 8–16 cores |
+| **RAM** | 8 GiB | 32–64 GiB |
+| **Storage** | 128 GiB SSD | 256–512 GiB SSD (or NVMe) |
+| **Network** | 1 Gbps | 1 Gbps (low latency to mobile clients) |
+
+- Prefer **SSD/NVMe** for database and backend data directories.
+- **Backups:** Use Proxmox backup or external backup for VM disks / PostgreSQL dumps and backend audit data.
+
+---
+
+## 5. Template contents checklist
+
+- **OS:** Debian 12 or Ubuntu 22.04 LTS (minimal/server).
+- **Java:** OpenJDK 17 (Eclipse Temurin) or Adoptium.
+- **Backend:** Install path for `smoa-backend-*.jar`; systemd unit; env file for `SERVER_PORT`, `SPRING_PROFILES_ACTIVE`, `SMOA_API_KEY`, `spring.datasource.url` (if PostgreSQL).
+- **Optional:** PostgreSQL 15+ (if not using H2); Nginx/Caddy for reverse proxy and TLS.
+- **Firewall:** Allow 8080 (backend) and 80/443 if reverse proxy; restrict admin/SSH.
+- **Persistent:** Separate disk or volume for data (H2 `./data/smoa` or PostgreSQL data dir) and logs; exclude from “golden” template so each clone gets its own data.
+
+---
+
+## 6. Summary table (single backend VM, no separate DB/proxy)
+
+| Component | vCPU | RAM | Disk | Network |
+|-----------|------|-----|------|---------|
+| **SMOA backend (all-in-one)** | 4 | 4 GiB | 40 GiB | 1 Gbps |
+| **Production (backend + PostgreSQL on same VM)** | 6 | 8 GiB | 80 GiB SSD | 1 Gbps |
+
+---
+
+## 7. All aspects which scale
+
+Every dimension below **scales** with load, retention, or features. The required target (Section above) is the floor; use this section to size for growth.
+
+| Aspect | What it scales with | How to scale | Config / notes |
+|--------|---------------------|--------------|----------------|
+| **vCPU (backend)** | Concurrent requests, JPA/DB work, sync bursts | Add vCPUs (4 → 6 → 8). Consider second backend instance + load balancer for high concurrency. | Spring Boot thread pool; no app config for vCPU. |
+| **RAM (backend)** | JVM heap, connection pools, cached entities, OS buffers | Increase VM RAM; set `-Xmx` (e.g. 1 GiB–2 GiB) leaving headroom for OS. | `JAVA_OPTS` or systemd `Environment`. |
+| **Disk (backend)** | H2/PostgreSQL data, log files, audit table (`sync_audit_log`) | Add disk or separate volume; rotate logs; archive/trim audit by date. | `spring.datasource.url`; logging config; optional audit retention job. |
+| **Network (backend)** | Request volume, payload size (sync/pull), rate limit | Bigger NIC or multiple backends behind proxy. | `smoa.rate-limit.requests-per-minute` (default 120 per key/IP). |
+| **Rate limit** | Number of clients and req/min per client | Increase `smoa.rate-limit.requests-per-minute` or disable for trusted LAN. | `application.yml` / env `SMOA_RATE_LIMIT_RPM`. |
+| **Concurrent devices (API)** | Sync + pull traffic from many devices | More backend vCPU/RAM; optional horizontal scaling (multiple backends + Nginx/Traefik). | No hard cap in app; rate limit is per key/IP. |
+| **Database size** | Directory, orders, evidence, credentials, reports, audit rows | More disk; move to dedicated PostgreSQL VM; indexes and vacuum. | `spring.datasource.*`; JPA/ddl-auto or Flyway. |
+| **Audit retention** | Compliance; `sync_audit_log` row count | More disk; periodic delete/archive by date; separate audit store. | Application-level job or DB cron. |
+| **vCPU (PostgreSQL)** | Query concurrency, connections, joins | Add vCPUs or move DB to dedicated VM with more cores. | `max_connections`, connection pool in backend. |
+| **RAM (PostgreSQL)** | Cache, working set | Increase VM RAM; tune `shared_buffers` / `work_mem`. | PostgreSQL config. |
+| **Disk (PostgreSQL)** | Tables, indexes, WAL | Add disk or volume; use SSD. | Data directory; backup size. |
+| **Reverse proxy** | TLS, load balancing, rate limiting | Add vCPU/RAM if many backends or heavy TLS; scale Nginx/Caddy workers. | Nginx `worker_processes`; upstreams. |
+| **TURN / signaling** | Concurrent WebRTC sessions, media bitrate | Scale vCPU (media encode/decode), RAM, and **network bandwidth**; add TURN instances for geography. | TURN/signaling server config; app `InfrastructureManager` endpoints. |
+| **Proxmox host CPU** | Sum of all VMs’ vCPU; burst load | Add physical cores; avoid overcommit (e.g. total vCPU &lt; 2× physical for production). | VM vCPU count. |
+| **Proxmox host RAM** | Sum of all VMs’ RAM | Add DIMMs; avoid overcommit. | VM RAM allocation. |
+| **Proxmox host disk** | All VMs + backups | Add disks or NAS; use SSD for DB and backend data. | VM disk size; backup retention. |
+| **Proxmox host network** | All VMs’ traffic; backup/restore | 1 Gbps minimum; 10 Gbps for many devices or TURN. | NIC; VLANs if needed. |
+
+### Scaling summary
+
+- **Backend only:** Scale **vCPU** and **RAM** for more concurrent devices and request spikes; **disk** for logs and audit.
+- **Backend + PostgreSQL:** Scale **DB disk** and **DB RAM** with data size and query load; **backend vCPU/RAM** with API load.
+- **With TURN/signaling:** Scale **TURN vCPU, RAM, and network** with concurrent WebRTC sessions and media bitrate.
+- **Multi-node:** Add more backend or TURN VMs and scale **reverse proxy** and **Proxmox host** to support them.
+
+These hardware requirements support the SMOA backend (sync, pull, delete, rate limiting, audit logging) and optional supporting infrastructure for a Proxmox VE template.
--- a/docs/infrastructure/k8s/backend-deployment.yaml
+++ b/docs/infrastructure/k8s/backend-deployment.yaml
@@ -0,0 +1,80 @@
+# Example Kubernetes Deployment and Service for SMOA backend.
+# Apply: kubectl apply -f docs/infrastructure/k8s/
+# Requires: backend image built (e.g. docker build -f backend/Dockerfile .) and pushed to your registry.
+
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: smoa-backend
+  labels:
+    app: smoa-backend
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: smoa-backend
+  template:
+    metadata:
+      labels:
+        app: smoa-backend
+    spec:
+      containers:
+        - name: backend
+          image: smoa-backend:1.0.0
+          imagePullPolicy: IfNotPresent
+          ports:
+            - containerPort: 8080
+          env:
+            - name: SPRING_PROFILES_ACTIVE
+              value: "prod"
+            - name: SMOA_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: smoa-secrets
+                  key: api-key
+            - name: SMOA_CORS_ORIGINS
+              valueFrom:
+                configMapKeyRef:
+                  name: smoa-config
+                  key: cors-origins
+                  optional: true
+          resources:
+            requests:
+              memory: "512Mi"
+              cpu: "250m"
+            limits:
+              memory: "1Gi"
+              cpu: "1000m"
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 8080
+            initialDelaySeconds: 30
+            periodSeconds: 10
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 8080
+            initialDelaySeconds: 10
+            periodSeconds: 5
+      restartPolicy: Always
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: smoa-backend
+  labels:
+    app: smoa-backend
+spec:
+  type: ClusterIP
+  ports:
+    - port: 8080
+      targetPort: 8080
+      protocol: TCP
+      name: http
+  selector:
+    app: smoa-backend
+---
+# Optional: create secret and configmap (replace values)
+# kubectl create secret generic smoa-secrets --from-literal=api-key=YOUR_API_KEY
+# kubectl create configmap smoa-config --from-literal=cors-origins=https://smoa.example.com
--- a/docs/infrastructure/nginx-smoa.conf.example
+++ b/docs/infrastructure/nginx-smoa.conf.example
@@ -0,0 +1,34 @@
+# Example Nginx config for SMOA backend (reverse proxy + TLS).
+# Place in /etc/nginx/sites-available/ and symlink to sites-enabled.
+# Replace smoa.example.com and paths with your values.
+
+upstream smoa_backend {
+    server 127.0.0.1:8080;
+    keepalive 32;
+}
+
+server {
+    listen 80;
+    server_name smoa.example.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name smoa.example.com;
+
+    ssl_certificate     /etc/ssl/certs/smoa.example.com.crt;
+    ssl_certificate_key /etc/ssl/private/smoa.example.com.key;
+    ssl_protocols       TLSv1.2 TLSv1.3;
+    ssl_ciphers         HIGH:!aNULL:!MD5;
+
+    location / {
+        proxy_pass http://smoa_backend;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Connection "";
+    }
+}