studio-admin-be/docs/image-build-limits.md

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).
• Admin Electron/AppImage jobs: dependency installation and packaging run in the same bounded worker, with secret build configuration and a local artifact exporter.
• 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:

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.

Admin Electron jobs have a 30-minute install/build timeout and a 4 GiB Node heap ceiling inside the aggregate 8 GiB worker limit. Git credentials and the admin API environment are not sent to the build context. No runtime image setting is required. The separate launcher-client Electron build path remains 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.