diff --git a/.gitignore b/.gitignore index 7e8128a7f..33de8ca89 100644 --- a/.gitignore +++ b/.gitignore @@ -72,3 +72,6 @@ servers.json config.*.json volatile/ + +# Local build override +docker-compose.override.yml \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index d7a9c6c80..739600e60 100644 --- a/AGENTS.md +++ b/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. diff --git a/README.md b/README.md index dabb953ec..c56dd7725 100644 --- a/README.md +++ b/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. +
diff --git a/doc/self-hosting.md b/doc/self-hosting.md index d470174e1..aaa310559 100644 --- a/doc/self-hosting.md +++ b/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 diff --git a/docker-compose.yml b/docker-compose.yml index 344555bfb..6ba505f5c 100644 --- a/docker-compose.yml +++ b/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: