docs/docs/system-requirements.md

La Suite Docs – System & Requirements (2025-06)

1. Quick-Reference Matrix (single VM / laptop)

Scenario	RAM	vCPU	SSD	Notes
Solo dev	8 GB	4	15 GB	Hot-reload + one IDE
Team QA	16 GB	6	30 GB	Runs integration tests
Prod ≤ 100 live users	32 GB	8 +	50 GB +	Scale linearly above this

Memory is the first bottleneck; CPU matters only when Celery or the Next.js build is saturated.

Note: Memory consumption varies by operating system. Windows tends to be more memory-hungry than Linux, so consider adding 10-20% extra RAM when running on Windows compared to Linux-based systems.

2. Development Environment Memory Requirements

Service	Typical use	Rationale / source
PostgreSQL	1 – 2 GB	shared_buffers starting point ≈ 25% RAM (postgresql.org)
Keycloak	≈ 1.3 GB	70% of limit for heap + ~300 MB non-heap (keycloak.org)
Redis	≤ 256 MB	Empty instance ≈ 3 MB; budget 256 MB to allow small datasets (stackoverflow.com)
MinIO	2 GB (dev) / 32 GB (prod)	Pre-allocates 1–2 GiB; docs recommend 32 GB per host for ≤ 100 Ti storage (min.io)
Django API (+ Celery)	0.8 – 1.5 GB	Empirical in-house metrics
Next.js frontend	0.5 – 1 GB	Dev build chain
Y-Provider (y-websocket)	< 200 MB	Large 40 MB YDoc called “big” in community thread (discuss.yjs.dev)
Nginx	< 100 MB	Static reverse-proxy footprint

Rule of thumb: add 2 GB for OS/overhead, then sum only the rows you actually run.

3. Production Environment Memory Requirements

Production deployments differ significantly from development environments. The table below shows typical memory usage for production services:

Service	Typical use	Rationale / notes
PostgreSQL	2 – 8 GB	Higher shared_buffers and connection pooling for concurrent users
OIDC Provider (optional)	Variable	Any OIDC-compatible provider (Keycloak, Auth0, Azure AD, etc.) - external or self-hosted
Redis	256 MB – 2 GB	Session storage and caching; scales with active user sessions
Object Storage (optional)	External or self-hosted	Can use AWS S3, Azure Blob, Google Cloud Storage, or self-hosted MinIO
Django API (+ Celery)	1 – 3 GB	Production workloads with background tasks and higher concurrency
Static Files (Nginx)	< 200 MB	Serves Next.js build output and static assets; no development overhead
Y-Provider (y-websocket)	200 MB – 1 GB	Scales with concurrent document editing sessions
Nginx (Load Balancer)	< 200 MB	Reverse proxy, SSL termination, static file serving

Production Architecture Notes

• Frontend: Uses pre-built Next.js static assets served by Nginx (no Node.js runtime needed)
• Authentication: Any OIDC-compatible provider can be used instead of self-hosted Keycloak
• Object Storage: External services (S3, Azure Blob) or self-hosted solutions (MinIO) are both viable
• Database: Consider PostgreSQL clustering or managed database services for high availability
• Scaling: Horizontal scaling is recommended for Django API and Y-Provider services

Minimal Production Setup (Core Services Only)

Service	Memory	Notes
PostgreSQL	2 GB	Core database
Django API (+ Celery)	1.5 GB	Backend services
Y-Provider	200 MB	Real-time collaboration
Nginx	100 MB	Static files + reverse proxy
Redis	256 MB	Session storage
Total (without auth/storage)	≈ 4 GB	External OIDC + object storage assumed

4. Recommended Software Versions

Tool	Minimum
Docker Engine / Desktop	24.0
Docker Compose	v2
Git	2.40
Node.js	22+
Python	3.13+
GNU Make	4.4
Kind	0.22
Helm	3.14
kubectl	1.29
mkcert	1.4

5. Ports (dev defaults)

Port	Service
3000	Next.js
8071	Django
4444	Y-Provider
8080	Keycloak
8083	Nginx proxy
9000/9001	MinIO
15432	PostgreSQL (main)
5433	PostgreSQL (Keycloak)
1081	MailCatcher

With fulltext search service

Port	Service
8081	Find (Django)
9200	Opensearch
9600	Opensearch admin
5601	Opensearch dashboard
25432	PostgreSQL (Find)

6. Sizing Guidelines

RAM – start at 8 GB dev / 16 GB staging / 32 GB prod. Postgres and Keycloak are the first to OOM; scale them first.

OS considerations: Windows systems typically require 10-20% more RAM than Linux due to higher OS overhead. Docker Desktop on Windows also uses additional memory compared to native Linux Docker.

CPU – budget one vCPU per busy container until Celery or Next.js builds saturate.

Disk – SSD; add 10 GB extra for the Docker layer cache.

MinIO – for demos, mount a local folder instead of running MinIO to save 2 GB+ of RAM.