docs/system-requirements.md
| 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.
| 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.
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 |
| 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 |
| 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 |
| 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) |
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.