smoa/docs/infrastructure/PROXMOX-VE-TEMPLATE-REQUIREMENTS.md

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 < 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.