Skip to content

Commit 3ad6d0e

Browse files
AntoLCAntoLC
committed
📝(project) add system-requirement doc
Add a new document detailing the system requirements for the project.
1 parent 9e8a7b3 commit 3ad6d0e

File tree

2 files changed

+111
-0
lines changed

2 files changed

+111
-0
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ and this project adheres to
1212

1313
- ✨(frontend) add customization for translations #857
1414
- 📝(project) add troubleshoot doc #1066
15+
- 📝(project) add system-requirement doc #1066
1516

1617
### Changed
1718

‎docs/system-requirements.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# La Suite Docs – System & Requirements (2025-06)
2+
3+
## 1. Quick-Reference Matrix (single VM / laptop)
4+
5+
| Scenario | RAM | vCPU | SSD | Notes |
6+
| ------------------------- | ----- | ---- | ------- | ------------------------- |
7+
| **Solo dev** | 8 GB | 4 | 15 GB | Hot-reload + one IDE |
8+
| **Team QA** | 16 GB | 6 | 30 GB | Runs integration tests |
9+
| **Prod ≤ 100 live users** | 32 GB | 8 + | 50 GB + | Scale linearly above this |
10+
11+
Memory is the first bottleneck; CPU matters only when Celery or the Next.js build is saturated.
12+
13+
> **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.
14+
15+
## 2. Development Environment Memory Requirements
16+
17+
| Service | Typical use | Rationale / source |
18+
| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------- |
19+
| PostgreSQL | **1 – 2 GB** | `shared_buffers` starting point ≈ 25% RAM ([postgresql.org][1]) |
20+
| Keycloak | **≈ 1.3 GB** | 70% of limit for heap + ~300 MB non-heap ([keycloak.org][2]) |
21+
| Redis | **≤ 256 MB** | Empty instance ≈ 3 MB; budget 256 MB to allow small datasets ([stackoverflow.com][3]) |
22+
| MinIO | **2 GB (dev) / 32 GB (prod)**| Pre-allocates 1–2 GiB; docs recommend 32 GB per host for ≤ 100 Ti storage ([min.io][4]) |
23+
| Django API (+ Celery) | **0.8 – 1.5 GB** | Empirical in-house metrics |
24+
| Next.js frontend | **0.5 – 1 GB** | Dev build chain |
25+
| Y-Provider (y-websocket) | **< 200 MB** | Large 40 MB YDoc called “big” in community thread ([discuss.yjs.dev][5]) |
26+
| Nginx | **< 100 MB** | Static reverse-proxy footprint |
27+
28+
[1]: https://www.postgresql.org/docs/9.1/runtime-config-resource.html "PostgreSQL: Documentation: 9.1: Resource Consumption"
29+
[2]: https://www.keycloak.org/high-availability/concepts-memory-and-cpu-sizing "Concepts for sizing CPU and memory resources - Keycloak"
30+
[3]: https://stackoverflow.com/questions/45233052/memory-footprint-for-redis-empty-instance "Memory footprint for Redis empty instance - Stack Overflow"
31+
[4]: https://min.io/docs/minio/kubernetes/upstream/operations/checklists/hardware.html "Hardware Checklist — MinIO Object Storage for Kubernetes"
32+
[5]: https://discuss.yjs.dev/t/understanding-memory-requirements-for-production-usage/198 "Understanding memory requirements for production usage - Yjs Community"
33+
34+
> **Rule of thumb:** add 2 GB for OS/overhead, then sum only the rows you actually run.
35+
36+
## 3. Production Environment Memory Requirements
37+
38+
Production deployments differ significantly from development environments. The table below shows typical memory usage for production services:
39+
40+
| Service | Typical use | Rationale / notes |
41+
| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------------- |
42+
| PostgreSQL | **2 – 8 GB** | Higher `shared_buffers` and connection pooling for concurrent users |
43+
| OIDC Provider (optional) | **Variable** | Any OIDC-compatible provider (Keycloak, Auth0, Azure AD, etc.) - external or self-hosted |
44+
| Redis | **256 MB – 2 GB** | Session storage and caching; scales with active user sessions |
45+
| Object Storage (optional)| **External or self-hosted** | Can use AWS S3, Azure Blob, Google Cloud Storage, or self-hosted MinIO |
46+
| Django API (+ Celery) | **1 – 3 GB** | Production workloads with background tasks and higher concurrency |
47+
| Static Files (Nginx) | **< 200 MB** | Serves Next.js build output and static assets; no development overhead |
48+
| Y-Provider (y-websocket) | **200 MB – 1 GB** | Scales with concurrent document editing sessions |
49+
| Nginx (Load Balancer) | **< 200 MB** | Reverse proxy, SSL termination, static file serving |
50+
51+
### Production Architecture Notes
52+
53+
- **Frontend**: Uses pre-built Next.js static assets served by Nginx (no Node.js runtime needed)
54+
- **Authentication**: Any OIDC-compatible provider can be used instead of self-hosted Keycloak
55+
- **Object Storage**: External services (S3, Azure Blob) or self-hosted solutions (MinIO) are both viable
56+
- **Database**: Consider PostgreSQL clustering or managed database services for high availability
57+
- **Scaling**: Horizontal scaling is recommended for Django API and Y-Provider services
58+
59+
### Minimal Production Setup (Core Services Only)
60+
61+
| Service | Memory | Notes |
62+
| ------------------------ | --------- | --------------------------------------- |
63+
| PostgreSQL | **2 GB** | Core database |
64+
| Django API (+ Celery) | **1.5 GB**| Backend services |
65+
| Y-Provider | **200 MB**| Real-time collaboration |
66+
| Nginx | **100 MB**| Static files + reverse proxy |
67+
| Redis | **256 MB**| Session storage |
68+
| **Total (without auth/storage)** | **≈ 4 GB** | External OIDC + object storage assumed |
69+
70+
## 4. Recommended Software Versions
71+
72+
| Tool | Minimum |
73+
| ----------------------- | ------- |
74+
| Docker Engine / Desktop | 24.0 |
75+
| Docker Compose | v2 |
76+
| Git | 2.40 |
77+
| **Node.js** | 22+ |
78+
| **Python** | 3.13+ |
79+
| GNU Make | 4.4 |
80+
| Kind | 0.22 |
81+
| Helm | 3.14 |
82+
| kubectl | 1.29 |
83+
| mkcert | 1.4 |
84+
85+
86+
## 5. Ports (dev defaults)
87+
88+
| Port | Service |
89+
| --------- | --------------------- |
90+
| 3000 | Next.js |
91+
| 8071 | Django |
92+
| 4444 | Y-Provider |
93+
| 8080 | Keycloak |
94+
| 8083 | Nginx proxy |
95+
| 9000/9001 | MinIO |
96+
| 15432 | PostgreSQL (main) |
97+
| 5433 | PostgreSQL (Keycloak) |
98+
| 1081 | MailCatcher |
99+
100+
## 6. Sizing Guidelines
101+
102+
**RAM** – start at 8 GB dev / 16 GB staging / 32 GB prod. Postgres and Keycloak are the first to OOM; scale them first.
103+
104+
> **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.
105+
106+
**CPU** – budget one vCPU per busy container until Celery or Next.js builds saturate.
107+
108+
**Disk** – SSD; add 10 GB extra for the Docker layer cache.
109+
110+
**MinIO** – for demos, mount a local folder instead of running MinIO to save 2 GB+ of RAM.

0 commit comments

Comments
 (0)