feat: cap controller container resources

Add cpus, mem_limit, memswap_limit, and pids_limit defaults to the
docker-git-api controller in docker-compose.yml and
docker-compose.api.yml. Each value is parameterized via a
DOCKER_GIT_CONTROLLER_* env var so operators can tune them.

Per-project containers already resolve a default 30% CPU/RAM cap
through resolveComposeResourceLimits, but the privileged controller
that orchestrates them had no caps and could consume the entire host.
This closes that gap so the whole system's resource footprint stays
bounded.

Closes #260

Author: konard

.changeset/cap-controller-resources.md

@@ -0,0 +1,13 @@
+---
+"@prover-coder-ai/docker-git": patch
+---
+
+feat: cap controller container CPU, memory, and PID consumption
+
+Adds default `cpus`, `mem_limit`, `memswap_limit`, and `pids_limit` to the
+`docker-git-api` controller in `docker-compose.yml` and
+`docker-compose.api.yml`. Each value is parameterized so operators can
+override it via `DOCKER_GIT_CONTROLLER_CPUS`, `DOCKER_GIT_CONTROLLER_MEMORY`,
+and `DOCKER_GIT_CONTROLLER_PIDS`. Defaults: 2 CPUs, 4 GiB RAM/swap, 4096 PIDs.
+This complements the existing per-project caps so a runaway controller
+cannot consume the entire host.

.gitkeep

@@ -113,3 +113,21 @@ When the CLI cannot acquire Docker access it now prints a message that
 names the specific failure mode, restates the host-Docker contract, and
 lists remediation steps for that exact mode. Implementation lives in
 `packages/app/src/docker-git/controller-docker-diagnostics.ts`.
+
+## Resource limits
+
+`docker-git` caps host resource consumption at two layers so a runaway
+project (or the controller itself) cannot consume the entire system.
+
+- **Per-project containers** ship with a default limit of `30%` CPU and
+  `30%` RAM (resolved against the host on `apply`). Override via
+  `--cpu` / `--ram` (or per-project `docker-git.json`).
+- **Controller container** (`docker-git-api`) is capped in
+  `docker-compose.yml` and `docker-compose.api.yml`. Override via
+  environment variables before `./ctl up`:
+
+  | Variable                       | Default | Purpose                              |
+  | ------------------------------ | ------- | ------------------------------------ |
+  | `DOCKER_GIT_CONTROLLER_CPUS`   | `2.0`   | Maximum CPU cores for the controller |
+  | `DOCKER_GIT_CONTROLLER_MEMORY` | `4g`    | Memory + swap cap (matched values)   |
+  | `DOCKER_GIT_CONTROLLER_PIDS`   | `4096`  | Maximum PIDs inside the controller   |

README.md

@@ -37,6 +37,10 @@ services:
     cgroup: host
     init: true
     restart: unless-stopped
+    cpus: ${DOCKER_GIT_CONTROLLER_CPUS:-2.0}
+    mem_limit: ${DOCKER_GIT_CONTROLLER_MEMORY:-4g}
+    memswap_limit: ${DOCKER_GIT_CONTROLLER_MEMORY:-4g}
+    pids_limit: ${DOCKER_GIT_CONTROLLER_PIDS:-4096}
 
 volumes:
   docker_git_projects:

docker-compose.api.yml

@@ -39,6 +39,10 @@ services:
     cgroup: host
     init: true
     restart: unless-stopped
+    cpus: ${DOCKER_GIT_CONTROLLER_CPUS:-2.0}
+    mem_limit: ${DOCKER_GIT_CONTROLLER_MEMORY:-4g}
+    memswap_limit: ${DOCKER_GIT_CONTROLLER_MEMORY:-4g}
+    pids_limit: ${DOCKER_GIT_CONTROLLER_PIDS:-4096}
 
 volumes:
   docker_git_projects:

docker-compose.yml

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { describe, expect, it } from "@effect/vitest"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const repoRoot = path.resolve(__dirname, "..", "..", "..", "..")
+
+const readComposeFile = (relativePath: string): string => readFileSync(path.join(repoRoot, relativePath), "utf8")
+
+const composeFiles = ["docker-compose.yml", "docker-compose.api.yml"] as const
+
+describe("controller compose resource limits", () => {
+  for (const composeFile of composeFiles) {
+    describe(composeFile, () => {
+      const contents = readComposeFile(composeFile)
+
+      it("caps controller CPU usage", () => {
+        expect(contents).toMatch(/cpus: \$\{DOCKER_GIT_CONTROLLER_CPUS:-\d+(?:\.\d+)?\}/u)
+      })
+
+      it("caps controller memory and swap together", () => {
+        expect(contents).toMatch(/mem_limit: \$\{DOCKER_GIT_CONTROLLER_MEMORY:-\d+[a-zA-Z]+\}/u)
+        expect(contents).toMatch(/memswap_limit: \$\{DOCKER_GIT_CONTROLLER_MEMORY:-\d+[a-zA-Z]+\}/u)
+      })
+
+      it("caps controller PIDs to prevent fork bombs", () => {
+        expect(contents).toMatch(/pids_limit: \$\{DOCKER_GIT_CONTROLLER_PIDS:-\d+\}/u)
+      })
+    })
+  }
+})