How builds work
How builds work
Every deployment starts with a build: your source code is transformed into a container image, pushed to the platform's internal registry, then deployed to the cluster.
The build pipeline
- Code retrieval: from the followed GitHub branch (or your upload).
- Stack detection: the auto builder analyzes the repository and picks the appropriate recipe (Node.js, Python, Go, PHP…).
- Image build: dependencies installed, build executed (
next build,vite build…), final image optimized. - Push to registry: the image is versioned in the internal registry, visible in the service's Registry tab.
- Deployment: the cluster switches to the new image with no downtime.
The two build modes
| Mode | When to use it |
|---|---|
| Auto build (default) | Most cases, no configuration |
| Dockerfile | You want full control over the image (guide) |
If a Dockerfile is present at the repository root, it can be used instead of automatic detection.
Following a build
The service's Deployments tab lists all builds with their status and full logs, kept even after the build finishes. A build in progress can be canceled at any time.
Build cache
Builds reuse a cache (dependencies, image layers) from one run to the next: a service's first build is the longest, later ones reuse everything that hasn't changed. If the cache has captured a stale dependency, Rebuild without cache from the service menu starts from scratch.
Node dependency handling
Whatever package manager your repository uses, builds run with npm. A bun.lock, pnpm-lock.yaml or yarn.lock is set aside before the build, and scripts calling those tools are rewritten to their npm equivalents. All of it happens on the working copy, never on your repository.
Your package-lock.json, on the other hand, is kept and used: the versions installed are exactly the ones it pins. That is what guarantees a production image ships the same dependencies as your machine.
It is set aside in two cases only, both announced in the build logs:
- it is out of sync with your
package.json, for instance because a dependency was added without regenerating the lock. Annpm installfollowed by committing the lock settles it; - your repository is managed by bun, pnpm or yarn (their file is the reference, and the
package-lock.jsonnext to it is not up to date).
In those two cases dependencies are simply re-resolved, and their versions may then differ from the ones on your machine.
A build fails? Open the logs of the failing build: the error is almost always there (missing dependency, failing
buildscript, runtime version). The Diagnose with AI button can also point you in the right direction (see AI assistant).
Go further
- Deployments and rollback
- The kx712.yml file: run tests before each deployment