|
1 | | -# System Requirements |
2 | | - |
3 | | -This document outlines the minimum and recommended system requirements for running La Suite Docs in both development and production environments. |
4 | | - |
5 | | -## Overview |
6 | | - |
7 | | -La Suite Docs is a comprehensive collaborative text editing platform that consists of multiple containerized services. The application architecture includes several components that require significant system resources to operate efficiently. |
8 | | - |
9 | | -## Architecture Components |
10 | | - |
11 | | -The application consists of the following main services: |
12 | | - |
13 | | -- **Backend (Django)**: Main application server with API endpoints |
14 | | -- **Frontend (Next.js)**: React-based user interface |
15 | | -- **Y-Provider**: Real-time collaboration service using Yjs |
16 | | -- **PostgreSQL**: Primary database (2 instances: main + Keycloak) |
17 | | -- **Redis**: Caching and session storage |
18 | | -- **Celery**: Background task processing |
19 | | -- **Keycloak**: Identity and access management |
20 | | -- **MinIO**: S3-compatible object storage |
21 | | -- **Nginx**: Reverse proxy and load balancer |
22 | | -- **MailCatcher**: Email testing (development only) |
23 | | - |
24 | | -## Minimum System Requirements |
25 | | - |
26 | | -### Hardware Requirements |
27 | | - |
28 | | -| Component | Minimum | Recommended | Notes | |
29 | | -|-----------|---------|-------------|-------| |
30 | | -| **RAM** | **16 GB** | **32 GB** | Critical for running all containers simultaneously | |
31 | | -| **CPU** | 4 cores | 8+ cores | Multi-core recommended for containerized workloads | |
32 | | -| **Storage** | 20 GB | 50+ GB | Includes Docker images, database, and media files | |
33 | | -| **Network** | 1 Gbps | 1 Gbps+ | For efficient container communication | |
34 | | - |
35 | | -### Software Requirements |
36 | | - |
37 | | -| Software | Version | Purpose | |
38 | | -|----------|---------|---------| |
39 | | -| **Docker** | 20.10+ | Container runtime | |
40 | | -| **Docker Compose** | 2.0+ | Multi-container orchestration | |
41 | | -| **Git** | 2.30+ | Source code management | |
42 | | - |
43 | | -#### Development Environment Additional Requirements |
44 | | - |
45 | | -| Software | Version | Purpose | |
46 | | -|----------|---------|---------| |
47 | | -| **GNU Make** | 3.8+ | Build automation | |
48 | | -| **Node.js** | 22+ | Frontend development | |
49 | | -| **Python** | 3.13+ | Backend development | |
50 | | -| **Yarn** | 1.22+ | Package management | |
51 | | - |
52 | | -#### Kubernetes Deployment Additional Requirements |
53 | | - |
54 | | -| Software | Version | Purpose | |
55 | | -|----------|---------|---------| |
56 | | -| **Kind** | 0.17+ | Local Kubernetes testing | |
57 | | -| **Helm** | 3.10+ | Kubernetes package manager | |
58 | | -| **Kubectl** | 1.25+ | Kubernetes CLI | |
59 | | -| **Mkcert** | 1.4+ | Local SSL certificates | |
60 | | - |
61 | | -## Performance Considerations |
62 | | - |
63 | | -### Memory Usage Breakdown |
64 | | - |
65 | | -The application's memory footprint is distributed across multiple containers: |
66 | | - |
67 | | -- **PostgreSQL (2 instances)**: ~2-4 GB |
68 | | -- **Django Backend + Celery**: ~2-3 GB |
69 | | -- **Frontend (Next.js)**: ~1-2 GB |
70 | | -- **Y-Provider (Yjs)**: ~1 GB |
71 | | -- **Keycloak**: ~1-2 GB |
72 | | -- **Redis**: ~500 MB |
73 | | -- **MinIO**: ~500 MB |
74 | | -- **Nginx**: ~100 MB |
75 | | -- **System overhead**: ~2-4 GB |
76 | | - |
77 | | -**Total estimated usage**: 10-16 GB under normal load |
78 | | - |
79 | | -### Why 32 GB RAM is Recommended |
80 | | - |
81 | | -- **Development hot-reloading**: Additional memory for file watching and compilation |
82 | | -- **Multiple environments**: Running tests, development, and production simultaneously |
83 | | -- **Database caching**: PostgreSQL and Redis benefit from additional memory |
84 | | -- **Build processes**: Docker image builds require temporary additional memory |
85 | | -- **IDE and development tools**: Additional overhead for development environment |
86 | | -- **OS and system processes**: Baseline system requirements |
87 | | - |
88 | | -## Storage Requirements |
89 | | - |
90 | | -### Disk Space Breakdown |
91 | | - |
92 | | -| Component | Space Recommended | Notes | |
93 | | -|-----------|----------------|-------| |
94 | | -| Docker images | 5-8 GB | All service images | |
95 | | -| Database data | 2-5 GB | Grows with usage | |
96 | | -| Media files | Variable | User-uploaded content | |
97 | | -| Logs | 1-2 GB | Application and container logs | |
98 | | -| Build cache | 3-5 GB | Docker layer cache for faster builds | |
99 | | - |
100 | | -### Recommended Storage Configuration |
101 | | - |
102 | | -- **SSD storage**: Recommended for database and container performance |
103 | | -- **Separate volumes**: Consider separate volumes for data persistence |
104 | | -- **Backup space**: Additional space for database and media backups |
105 | | - |
106 | | -## Network Requirements |
107 | | - |
108 | | -### Port Usage |
109 | | - |
110 | | -The application uses the following ports in development: |
111 | | - |
112 | | -| Port | Service | Description | |
113 | | -|------|---------|-------------| |
114 | | -| 3000 | Frontend | Next.js development server | |
115 | | -| 8071 | Backend | Django development server | |
116 | | -| 8080 | Keycloak | Identity management | |
117 | | -| 8083 | Nginx | Reverse proxy | |
118 | | -| 4444 | Y-Provider | Real-time collaboration | |
119 | | -| 9000/9001 | MinIO | Object storage | |
120 | | -| 15432 | PostgreSQL | Main database | |
121 | | -| 5433 | PostgreSQL | Keycloak database | |
122 | | -| 1081 | MailCatcher | Email testing | |
123 | | - |
124 | | -### Firewall Configuration |
125 | | - |
126 | | -For production deployment, ensure the following ports are properly configured: |
127 | | -- **80/443**: HTTP/HTTPS traffic |
128 | | -- **Internal networking**: Allow container-to-container communication |
129 | | -- **Database ports**: Restrict access to trusted sources only |
130 | | - |
131 | | -## Operating System Compatibility |
132 | | - |
133 | | -### Supported Operating Systems |
134 | | - |
135 | | -| OS | Version | Notes | |
136 | | -|----|---------|-------| |
137 | | -| **Linux** | Ubuntu 20.04+, CentOS 8+, Debian 11+ | Recommended for production | |
138 | | -| **macOS** | 11.0+ (Big Sur) | Development environment | |
139 | | -| **Windows** | 10/11 with WSL2 | Development environment | |
140 | | - |
141 | | -### Container Runtime |
142 | | - |
143 | | -- **Docker Desktop**: Recommended for development on macOS/Windows |
144 | | -- **Docker Engine**: Recommended for Linux production environments |
145 | | -- **Resource allocation**: Configure Docker with adequate memory and CPU limits |
146 | | - |
147 | | -## Performance Optimization Tips |
148 | | - |
149 | | -### Docker Configuration |
150 | | - |
151 | | -```bash |
152 | | -# Recommended Docker Desktop settings |
153 | | -Memory: 8-16 GB |
154 | | -CPUs: 4-8 cores |
155 | | -Swap: 2 GB |
156 | | -Disk image size: 50+ GB |
157 | | -``` |
158 | | - |
159 | | -### System Optimization |
160 | | - |
161 | | -1. **Increase file watchers** (Linux): |
162 | | - ```bash |
163 | | - echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf |
164 | | - sudo sysctl -p |
165 | | - ``` |
166 | | - |
167 | | -2. **Optimize Docker daemon** (`/etc/docker/daemon.json`): |
168 | | - ```json |
169 | | - { |
170 | | - "log-driver": "json-file", |
171 | | - "log-opts": { |
172 | | - "max-size": "10m", |
173 | | - "max-file": "3" |
174 | | - } |
175 | | - } |
176 | | - ``` |
177 | | - |
178 | | -3. **Use Docker BuildKit** for faster builds: |
179 | | - ```bash |
180 | | - export DOCKER_BUILDKIT=1 |
181 | | - ``` |
182 | | - |
183 | | -## Production Considerations |
184 | | - |
185 | | -### Scaling Requirements |
186 | | - |
187 | | -For production environments with multiple users: |
188 | | - |
189 | | -- **Memory**: Scale linearly with concurrent users (1-2 GB per 100 concurrent users) |
190 | | -- **CPU**: Consider auto-scaling based on load |
191 | | -- **Database**: Separate database server with adequate IOPS |
192 | | -- **Storage**: High-performance storage for database and shared media |
193 | | - |
194 | | -### Monitoring |
195 | | - |
196 | | -Implement monitoring for: |
197 | | -- Container resource usage |
198 | | -- Database performance |
199 | | -- Memory utilization |
200 | | -- Disk I/O and space |
201 | | -- Network throughput |
202 | | - |
203 | | -## Troubleshooting Common Issues |
204 | | - |
205 | | -### Out of Memory Errors |
206 | | - |
207 | | -- Increase Docker memory allocation |
208 | | -- Check for memory leaks in application logs |
209 | | -- Consider reducing the number of concurrent services |
210 | | - |
211 | | -### Slow Performance |
212 | | - |
213 | | -- Verify adequate RAM allocation |
214 | | -- Check disk I/O performance |
215 | | -- Monitor network latency between containers |
216 | | -- Review Docker resource limits |
217 | | - |
218 | | -### Build Failures |
219 | | - |
220 | | -- Ensure adequate disk space for Docker builds |
221 | | -- Increase Docker memory allocation |
222 | | -- Clear Docker build cache if needed |
223 | | - |
224 | | -## Getting Help |
225 | | - |
226 | | -If you encounter resource-related issues: |
227 | | - |
228 | | -1. Check the [troubleshooting documentation](./troubleshoot.md) |
229 | | -2. Monitor system resources during operation |
230 | | -3. Review Docker and application logs |
231 | | -4. Consider adjusting resource allocation based on usage patterns |
232 | | - |
233 | | -For more information about installation and deployment, see: |
234 | | -- [Installation Guide](./installation.md) |
235 | | -- [Environment Variables](./env.md) |
236 | | -- [Architecture Overview](./architecture.md) |
| 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.12+ | |
| 79 | +| GNU Make | 4.4 | |
| 80 | +| Kind | 0.22 | |
| 81 | +| Helm | 3.14 | |
| 82 | +| kubectl | 1.29 | |
| 83 | +| mkcert | 1.4 | |
| 84 | + |
| 85 | +[1]: https://nodejs.org/en/about/previous-releases "Node.js — Node.js Releases" |
| 86 | +[2]: https://www.python.org/downloads/release/python-3120/ "Python Release Python 3.12.0 | Python.org" |
| 87 | + |
| 88 | +## 5. Ports (dev defaults) |
| 89 | + |
| 90 | +| Port | Service | |
| 91 | +| --------- | --------------------- | |
| 92 | +| 3000 | Next.js | |
| 93 | +| 8071 | Django | |
| 94 | +| 4444 | Y-Provider | |
| 95 | +| 8080 | Keycloak | |
| 96 | +| 8083 | Nginx proxy | |
| 97 | +| 9000/9001 | MinIO | |
| 98 | +| 15432 | PostgreSQL (main) | |
| 99 | +| 5433 | PostgreSQL (Keycloak) | |
| 100 | +| 1081 | MailCatcher | |
| 101 | + |
| 102 | +## 6. Sizing Guidelines |
| 103 | + |
| 104 | +**RAM** – start at 8 GB dev / 16 GB staging / 32 GB prod. Postgres and Keycloak are the first to OOM; scale them first. |
| 105 | + |
| 106 | +> **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. |
| 107 | +
|
| 108 | +**CPU** – budget one vCPU per busy container until Celery or Next.js builds saturate. |
| 109 | + |
| 110 | +**Disk** – SSD; add 10 GB extra for the Docker layer cache. |
| 111 | + |
| 112 | +**MinIO** – for demos, mount a local folder instead of running MinIO to save 2 GB+ of RAM. |
0 commit comments