Build on another server

By default a project is built on the server it runs on. A big next build, a Rust compile or a Buildpacks run then competes with your live apps for CPU, memory and disk. Build on moves the build to another of your servers: the image is built there and then sent to the deploy server, which only has to load it and start the container.

Nothing else about the build changes. The same builder runs (Auto with Synq's generated Dockerfiles, your Dockerfile, Nixpacks, Railpack or Buildpacks), with the same settings, the same build log and the same Cancel button.

Set up a build server

A compose or monorepo project uses the same card: every service image is built on the build server and sent to the deploy server as soon as it is ready, while the build server moves on to the next service.

What happens during a deploy

1. Checks before anything is cloned. Synq connects to the build server and checks that it still builds for other servers, that Docker answers, that its CPU architecture matches the deploy server's, and that it has at least 2 GB of disk left for Docker.
2. The build runs on the build server exactly like a build on the deploy server. Clone on the server, per-server GitHub access and forwarded git credentials apply to the build server, because that is where the source is fetched. Project variables reach the build as a BuildKit secret, never as an image layer or a command-line argument.
3. The hand-off. Synq checks the image's CPU architecture and that the deploy server has room for it, then streams docker save from the build server into docker load on the deploy server through the SSH connections the panel already holds. The stream is compressed with zstd when both servers have zstd, otherwise gzip. Nothing is written to a temporary file, no registry is involved, and no port is opened on either server.
4. Verification. On the deploy server Synq inspects the loaded image and compares it with the one that was built: the same image ID, or, when the two Docker daemons use different image stores, the same layers, platform and container settings. An image that does not match is deleted and the deploy fails.
5. Clean up. The image is removed from the build server. On the deploy server it carries the usual tag and labels, so rollbacks, the rollback window and image cleanup treat it like any other build.

The bytes travel from the build server to the machine running the panel and on to the deploy server. When the panel runs on your laptop (the desktop app), keep the image size in mind.

Build cache

The build cache stays on the build server: BuildKit's layer cache and the package-manager caches that Synq's generated Dockerfiles mount are reused by the next build of the project there. Clear build cache on a project that builds elsewhere clears the build server's cache. The daily build-cache sweep keeps every server's cache under 10 GB, build servers included.

A build server without the docker buildx plugin uses Docker's legacy builder, which keeps no cache between remote builds (the image is removed after the hand-off) and cannot pass variables as secrets. Install docker-buildx-plugin on build servers.

When the build server can't build

To build on the deploy server instead of failing in the first four cases, turn on Build on the deploy server if this one is unavailable in the Build on card. The deploy log then says why it fell back. It is off by default: when you move builds off production, production should not start building on its own.

Cancelling

Cancel stops the build on the build server (its docker build and any build containers there) and stops an image transfer that is under way. An image that was already loaded on the deploy server for the cancelled deploy is removed again.

What always builds on the deploy server

• Static sites. Their files are extracted from the build container into the folder the edge serves, on the deploy server. In a compose project, static services build on the deploy server while the other services build on the build server.
• Projects that deploy a prebuilt image and rollbacks that restore a kept image build nothing.
• Apps that run directly on the host (without Docker), Synq Cloud projects and cluster projects, which have builders of their own.
• App templates with an inline Dockerfile (one-click apps that ship their own build files).

From the API

Turn a server into a build server, then point a project at it:

curl -X PATCH -H "Authorization: Bearer $SYNQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"buildServer":true}' \
  "$SYNQ_URL/api/system/servers/$BUILD_SERVER_ID"

curl -X PATCH -H "Authorization: Bearer $SYNQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"buildServerId":"'"$BUILD_SERVER_ID"'","buildServerFallback":false}' \
  "$SYNQ_URL/api/projects/$PROJECT_ID"

Send "buildServerId":null to build on the deploy server again. The server must belong to the project's organization and have buildServer on, or the request fails with 400.

Related guides