What happens inside a build - Cloud Build steps, generated Dockerfiles, lockfile-exact installs, static uploads, and reading a failed build.
Builds
Every deploy starts with a build: the commit is turned into either a folder of static files or a container image. This page is what happens inside that step.
The steps#
A build runs on Cloud Build and streams its progress into the deploy record:
- Fetch. The commit is checked out. Apps with a root directory build from that folder.
- Install. Dependencies are installed with the install command - by default, the package manager your lockfile implies.
- Build. The build command runs. For containers this happens inside the image build.
- Package. A static build's output directory is uploaded to object storage; a container image is pushed to Artifact Registry.
- Release. The CDN starts serving the new files, or Cloud Run shifts traffic to the new revision.
Watch it live in the build logs; each deploy keeps its full log.
Dockerfiles: generated or your own#
A Dockerfile in the repository always wins - the app builds and runs exactly as written, whatever is inside. See Deploy with a Dockerfile.
Without one, Light Cloud generates a Dockerfile for the detected framework:
- Generated Node images run on Node 22.
- The install step follows your lockfile -
pnpm-lock.yaml,yarn.lock, orpackage-lock.jsondecide the package manager, and with a lockfile present installs are exact (npm ciand equivalents). - The image runs your server on the configured port, with
PORTset in the environment.
Environment variables at build time#
- Static builds run the build command with the environment's variables set - inlined values (
NEXT_PUBLIC_*,VITE_*) work as usual. - Container images are built without your runtime variables. Read configuration at startup, not at image build time - the same image may serve an environment whose variables have changed since.
When a build fails#
The deploy is marked failed and nothing is released - the previous deploy keeps serving. The lines that broke the build are pulled out of the build output and put on the deploy record, so the reason is on screen without digging.
Common causes, in the order they usually bite:
| Symptom | Usual cause | Fix |
|---|---|---|
| Install step fails | Lockfile out of sync with package.json | Reinstall locally, commit the lockfile |
| Build command fails | Type errors, missing build-time variable | Read the extracted lines; set the variable on the environment |
| Output directory empty | Framework writes somewhere else | Match output directory to your config |
| Green build, unreachable app | Server listens on the wrong port | Match the port or read PORT at startup |
A failed build costs its build minutes and nothing else.