feat(api): add resource limits configuration endpoint

This commit introduces a new API endpoint (`GET /api/limits`) that retrieves the current resource limit configurations for workspace management. This includes parameters such as maximum concurrent workspaces, CPU and memory limits per workspace, and whether resource limits enforcement is enabled.

Additionally, the frontend has been updated to load these resource limits dynamically, ensuring users can only select values within the configured limits when setting up their workspaces. This enhancement aims to improve user experience by preventing resource over-allocation and system overload.

Documentation for the new endpoint has been added to API.md, and existing sections in ARCHITECTURE.md and INSTALLATION.md have been updated to reflect these changes.

Author: Frederik Wystup

docs/API.md

@@ -328,6 +328,36 @@ Retrieves platform configuration information.
 }
 ```
 
+### Resource Limits Configuration
+
+Retrieves current resource limit configuration for workspace management.
+
+**Endpoint**: `GET /api/limits`
+
+**Response**:
+```json
+{
+  "maxConcurrentWorkspaces": 5,
+  "cpuPerWorkspace": 4.0,
+  "memoryPerWorkspaceMB": 8192,
+  "enableResourceLimits": true
+}
+```
+
+**Parameters**:
+- `maxConcurrentWorkspaces` (integer): Maximum number of simultaneously running workspaces
+- `cpuPerWorkspace` (number): Maximum CPU cores allocated per workspace
+- `memoryPerWorkspaceMB` (integer): Maximum RAM in megabytes per workspace
+- `enableResourceLimits` (boolean): Whether resource limit enforcement is enabled
+
+**Usage**:
+```bash
+# Check current resource limits
+curl http://localhost/api/limits
+```
+
+This endpoint is used by the frontend to dynamically populate resource selection options, ensuring users can only choose values within configured limits.
+
 ## Git Integration
 
 ### List Git Repositories
@@ -410,6 +440,7 @@ All error responses follow this format:
 | 401 | `INVALID_WORKSPACE_PASSWORD` | Incorrect workspace password |
 | 404 | `PROJECT_NOT_FOUND` | Project ID does not exist |
 | 409 | `WORKSPACE_LIMIT_EXCEEDED` | Maximum workspaces per user reached |
+| 409 | `CONCURRENT_LIMIT_REACHED` | Maximum concurrent workspaces reached |
 | 500 | `CONTAINER_CREATE_FAILED` | Failed to create Docker container |
 | 500 | `GIT_REPO_CREATE_FAILED` | Failed to create Git repository |
 | 503 | `SERVICE_UNAVAILABLE` | Docker daemon or system unavailable |

docs/ARCHITECTURE.md

@@ -216,9 +216,30 @@ deploy:
       memory: 1G
 ```
 
+**Resource Limits Configuration**:
+XaresAICoder implements configurable resource limits to prevent system overload:
+
+- **Concurrent Workspace Limits**: Maximum number of simultaneously running workspaces (default: 3)
+- **Per-Workspace CPU**: Maximum CPU cores per workspace (default: 1.0)
+- **Per-Workspace Memory**: Maximum RAM per workspace in MB (default: 4096)
+
+Configuration via environment variables:
+```bash
+MAX_CONCURRENT_WORKSPACES=3
+CPU_PER_WORKSPACE=1.0
+MEMORY_PER_WORKSPACE_MB=4096
+ENABLE_RESOURCE_LIMITS=true
+```
+
+**Enforcement Mechanisms**:
+- **Backend**: Concurrent limit checked in `createProject()` and `startProject()` methods
+- **Frontend**: Dynamic select box population prevents users from selecting values beyond limits
+- **Docker**: Resource limits enforced via Docker's HostConfig.Memory and HostConfig.CpuShares
+- **API Endpoint**: `/api/limits` exposes current configuration to frontend
+
 **System Services**:
 - nginx: 128MB RAM, 0.1 CPU
-- server: 512MB RAM, 0.5 CPU  
+- server: 512MB RAM, 0.5 CPU
 - forgejo: 1GB RAM, 0.5 CPU
 
 ### Volume Management

docs/INSTALLATION.md

@@ -157,6 +157,10 @@ curl http://localhost/api/health
 | `WORKSPACE_TIMEOUT_MINUTES` | 120 | Workspace auto-stop timeout |
 | `MAX_WORKSPACES_PER_USER` | 5 | Maximum workspaces per user |
 | `ENABLE_GIT_SERVER` | false | Enable integrated Forgejo Git server |
+| `MAX_CONCURRENT_WORKSPACES` | 3 | Maximum concurrent running workspaces |
+| `CPU_PER_WORKSPACE` | 1.0 | CPU cores allocated per workspace |
+| `MEMORY_PER_WORKSPACE_MB` | 4096 | RAM in MB per workspace |
+| `ENABLE_RESOURCE_LIMITS` | true | Enable resource limit enforcement |
 
 ### Git Server Configuration
 
@@ -428,20 +432,52 @@ docker compose up -d
 
 ### Resource Limits
 
-Edit `docker-compose.yml` to adjust resource limits:
+XaresAICoder supports configurable resource limits to prevent system overload. Configure via `.env` file:
 
-```yaml
-services:
-  # Per-workspace limits
-  deploy:
-    resources:
-      limits:
-        cpus: '2.0'
-        memory: 4G
-      reservations:
-        memory: 1G
+```bash
+# Maximum concurrent workspaces
+MAX_CONCURRENT_WORKSPACES=3
+
+# CPU cores per workspace
+CPU_PER_WORKSPACE=1.0
+
+# Memory in MB per workspace
+MEMORY_PER_WORKSPACE_MB=4096
+
+# Enable resource limit enforcement
+ENABLE_RESOURCE_LIMITS=true
+```
+
+**Configuration Examples**:
+
+**Personal Development** (default):
+```bash
+MAX_CONCURRENT_WORKSPACES=3
+CPU_PER_WORKSPACE=1.0
+MEMORY_PER_WORKSPACE_MB=4096
+```
+
+**Powerful Workstation**:
+```bash
+MAX_CONCURRENT_WORKSPACES=10
+CPU_PER_WORKSPACE=2.0
+MEMORY_PER_WORKSPACE_MB=8192
+```
+
+**Shared Server** (conservative):
+```bash
+MAX_CONCURRENT_WORKSPACES=5
+CPU_PER_WORKSPACE=0.5
+MEMORY_PER_WORKSPACE_MB=2048
 ```
 
+**Check Current Limits**:
+```bash
+curl http://localhost/api/limits
+```
+
+See [README - Resource Limits](../README.md#resource-limits) for detailed information.
+
 ### Storage Configuration
 
 ```bash

frontend/app.js

@@ -103,6 +103,90 @@ class XaresAICoder {
                 protocol: 'http'
             };
         }
+
+        // Load resource limits
+        await this.loadResourceLimits();
+    }
+
+    async loadResourceLimits() {
+        try {
+            const response = await fetch(`${this.apiBase}/limits`);
+            const data = await response.json();
+
+            if (response.ok) {
+                this.limits = data;
+                console.log('Resource limits loaded:', this.limits);
+
+                // Populate select boxes based on limits
+                this.populateResourceSelects();
+            } else {
+                console.error('Failed to load resource limits:', data);
+                // Set default limits
+                this.limits = {
+                    maxConcurrentWorkspaces: 3,
+                    cpuPerWorkspace: 1.0,
+                    memoryPerWorkspaceMB: 4096,
+                    enableResourceLimits: true
+                };
+                this.populateResourceSelects();
+            }
+        } catch (error) {
+            console.error('Error loading resource limits:', error);
+            // Set default limits
+            this.limits = {
+                maxConcurrentWorkspaces: 3,
+                cpuPerWorkspace: 1.0,
+                memoryPerWorkspaceMB: 4096,
+                enableResourceLimits: true
+            };
+            this.populateResourceSelects();
+        }
+    }
+
+    populateResourceSelects() {
+        // Memory options in MB
+        const memoryOptions = [
+            { value: '1g', mb: 1024, label: '1 GB RAM' },
+            { value: '2g', mb: 2048, label: '2 GB RAM' },
+            { value: '4g', mb: 4096, label: '4 GB RAM' },
+            { value: '8g', mb: 8192, label: '8 GB RAM' },
+            { value: '16g', mb: 16384, label: '16 GB RAM' }
+        ];
+
+        // CPU options
+        const cpuOptions = [
+            { value: '1', cores: 1, label: '1 Core' },
+            { value: '2', cores: 2, label: '2 Cores' },
+            { value: '4', cores: 4, label: '4 Cores' },
+            { value: '8', cores: 8, label: '8 Cores' }
+        ];
+
+        // Filter options based on limits
+        const maxMemoryMB = this.limits.memoryPerWorkspaceMB || 4096;
+        const maxCpu = this.limits.cpuPerWorkspace || 2.0;
+
+        const availableMemoryOptions = memoryOptions.filter(opt => opt.mb <= maxMemoryMB);
+        const availableCpuOptions = cpuOptions.filter(opt => opt.cores <= maxCpu);
+
+        // Populate memory select
+        const memorySelect = document.getElementById('memoryLimit');
+        if (memorySelect) {
+            memorySelect.innerHTML = availableMemoryOptions.map((opt, index) => {
+                // Set 2GB as default, or the highest available if 2GB not available
+                const isDefault = opt.value === '2g' || (opt.mb === maxMemoryMB && maxMemoryMB < 2048);
+                return `<option value="${opt.value}" ${isDefault ? 'selected' : ''}>${opt.label}${isDefault && opt.value === '2g' ? ' (Default)' : ''}${opt.mb === maxMemoryMB ? ' (Max)' : ''}</option>`;
+            }).join('');
+        }
+
+        // Populate CPU select
+        const cpuSelect = document.getElementById('cpuCores');
+        if (cpuSelect) {
+            cpuSelect.innerHTML = availableCpuOptions.map((opt, index) => {
+                // Set 2 cores as default, or the highest available if 2 cores not available
+                const isDefault = opt.value === '2' || (opt.cores === maxCpu && maxCpu < 2);
+                return `<option value="${opt.value}" ${isDefault ? 'selected' : ''}>${opt.label}${isDefault && opt.value === '2' ? ' (Default)' : ''}${opt.cores === maxCpu ? ' (Max)' : ''}</option>`;
+            }).join('');
+        }
     }
 
     setupUI() {