docs: document local Docker builds with Compose overrides (#3867)

.gitignore

@@ -72,3 +72,6 @@ servers.json
 config.*.json
 
 volatile/
+
+# Local build override
+docker-compose.override.yml

AGENTS.md

@@ -58,6 +58,36 @@ When in doubt, return less. Auth-, permission-, or data-export-related changes d
 
 ---
 
+## Local development configuration
+
+To test a local Docker build, create `docker-compose.override.yml` in the repository
+root (or merge into the existing file):
+
+```yaml
+services:
+  puter:
+    pull_policy: never
+    build:
+      context: .
+```
+
+Compose merges it automatically. Run `docker compose up -d --build` to build and
+start the stack, and repeat after source changes. Keep local build settings in
+this gitignored override instead of editing `docker-compose.yml`, so they stay
+out of pull requests and do not conflict when pulling updates. See
+[Self-Hosting Puter](doc/self-hosting.md#building-from-source-instead-of-pulling)
+for the required runtime configuration.
+
+For local API testing, agents may decide whether to set `"unlimitedMetering": true`
+when budget checks block unrelated tests; no additional approval is needed.
+Merge it into the ignored `config.json` for `npm start` or
+`puter/config/config.json` for Docker, then restart Puter. It applies to all
+accounts on that local instance, including guests, and usage is still recorded.
+Keep normal settings when testing budget or subscription enforcement, and leave
+shared defaults unchanged.
+
+---
+
 ## Backend
 
 A layered stack with explicit dependency injection: each layer depends only on the layers beneath it, receives them through its constructor, and `PuterServer` ([src/backend/server.ts](src/backend/server.ts)) wires the whole thing together. [doc/architecture.md](doc/architecture.md) is the full reference.

README.md

@@ -46,6 +46,8 @@ npm start
 ```
 **→** This should launch Puter at  http://puter.localhost:4100
 
+To run this checkout with Docker, follow [Building from source](./doc/self-hosting.md#building-from-source-instead-of-pulling). Create a local `docker-compose.override.yml` to select the local build; keeping these settings out of `docker-compose.yml` avoids conflicts when pulling updates and keeps local configuration out of pull requests.
+
 
 <br/>
 

doc/self-hosting.md

@@ -408,6 +408,12 @@ Every account then resolves to an unlimited policy. Usage is still recorded, so
 the dashboard still shows what is being consumed; nothing is ever refused for
 lack of budget.
 
+For API testing, you can also set `"unlimitedMetering": true` in your
+ignored runtime config: `puter/config/config.json` for Docker, or the repository's
+`config.json` for `npm start`. Merge it into the existing config and restart Puter.
+This includes guest accounts and applies to the whole local instance. Keep normal
+metering settings when testing budget or subscription enforcement.
+
 To keep the budgets but stop them blocking anything — recording only:
 
 ```json
@@ -488,12 +494,36 @@ For GPU acceleration (NVIDIA), uncomment the `deploy:` block under the `ollama`
 
 ## Building from source instead of pulling
 
-If you want to test local Dockerfile changes against the full stack, uncomment the `build:` block in [docker-compose.yml](../docker-compose.yml) under the `puter` service, change `pull_policy: always` → `pull_policy: never`, then:
+To run a local build against the full stack, use a source checkout and complete
+the configuration steps above. Create `docker-compose.override.yml` in the
+repository root, next to [docker-compose.yml](../docker-compose.yml):
+
+```yaml
+services:
+  puter:
+    pull_policy: never
+    build:
+      context: .
+```
+
+If that file already exists, merge these settings into its `puter` service.
+Compose loads and merges the override automatically. `build.context: .` selects
+this checkout, and `pull_policy: never` prevents pulling the published Puter image.
+
+Use this override for local build settings instead of editing `docker-compose.yml`.
+The override is ignored by Git, keeping local configuration out of pull requests
+and avoiding conflicts in the shared Compose file when pulling updates.
+
+From the repository root, build and start the stack:
 
 ```bash
 docker compose up -d --build
 ```
 
+Run the same command after changing or pulling source code to rebuild the image.
+To return to the published image, remove the local build settings (or the override
+file if those are its only settings), then run `docker compose up -d`.
+
 ---
 
 ## Managing running backend

docker-compose.yml

@@ -230,15 +230,8 @@ services:
   puter:
     image: ghcr.io/heyputer/puter:main
     pull_policy: always
-    # Uncomment to build from this directory instead of pulling the published
-    # image. Also flip pull_policy to `never` so compose doesn't overwrite
-    # your local build by re-pulling :latest.
-    # build:
-    #   context: .
-    #   # buildx-only: cross-compile to both archs in a single push
-    #   # platforms:
-    #   #   - linux/amd64
-    #   #   - linux/arm64
+    # For local builds, create a docker-compose.override.yml;
+    # see doc/self-hosting.md#building-from-source-instead-of-pulling.
     container_name: puter
     restart: unless-stopped
     depends_on: