# Container image build limits

`scripts/build-image.sh` submits image builds to one Docker-container BuildKit
worker named `studio-limited0` (container `buildx_buildkit_studio-limited0`).
The shared worker has an aggregate 2-CPU quota, 8 GiB memory limit, no swap, and
at most two parallel build steps. Concurrent API/CI image builds share these
limits instead of each getting a separate allowance.

The wrapper explicitly selects this worker and verifies its driver, node and
Docker resource configuration before building. Missing Buildx or mismatched
limits fail the build, with no unrestricted fallback. The result is loaded into
Docker so existing push/deployment steps are unchanged. No global Docker daemon
settings or default builder selection are changed.

## Covered source paths

- Admin app component image builds (including LMS FE/BE web images).
- Launcher backend image builds.
- Woodpecker image-build steps for admin FE/BE, auth, platform gateway and manual.

The admin runtime includes Buildx and a copy of the wrapper/config. Other
Woodpecker projects mount the host directory below read-only and invoke the same
wrapper. Rollout of these source changes is required; preparing the worker alone
does not redirect existing callers.

## Server setup

Copy `scripts/build-image.sh` and `scripts/buildkitd.toml` to
`/home/future2/Studio_v2/build-tools/` before deploying the pipeline changes.
Do not remove this directory while those pipelines reference it.

The old host Buildx 0.10.5 does not support the required CPU driver options.
Use the existing Docker 27 CLI image to prepare the worker without replacing the
host CLI or restarting services:

```sh
docker run --rm --cpus=0.5 --memory=128m --memory-swap=128m \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /home/future2/Studio_v2/build-tools:/tools:ro \
  docker:27-cli sh /tools/build-image.sh --prepare-only
```

BuildKit's existing server image is pinned by digest, independently of app
versions. Its host network mode supports the existing localhost:5000 registry;
this is a trusted build service, not an untrusted-code security sandbox.

No `BUILD_ARTIFACT_IMAGE` or per-app build image setting is required.

## Scope and rollout limitations

This is not a daemon-wide enforcement mechanism: arbitrary `docker build`,
unmodified GitHub Actions `setup-buildx-action`/`build-push-action` workflows, and
other builders do not automatically use this worker. Those workflows must also
be routed explicitly before claiming every image build on the server is limited.
Do not let CI cleanup remove the shared builder after each job.

Electron/npm builds outside Docker image builds are separate and unchanged.
This does not diagnose or guarantee prevention of power, hardware or kernel
failures. Runtime service limits, deployment behavior and database migrations
are not modified.

Tests: `node --test scripts/build-image.test.cjs` and `npx tsc --noEmit`.