Build servers

Use it when builds are competing with production for CPU, or when several small servers can share one larger builder.

A build server uses the Build only role. It gets Docker and address pools, but no Traefik and never appears as a deploy target.

The builder sends the image to the target host through the control plane. The deploy uses a slot in the builder's queue.

Build logs still belong to the app. Read them where you always do.

When the builder is downCopy Anchor Link

A deploy still ships. Deplo tries, in order:

1. The app's build server.
2. Every server marked Build as a fallback, the Deplo host first.
3. The server the app runs on.

The first host that answers compiles it, and the deploy log names it.

A host is only tried when Deplo can see it is healthy: one that is offline, one whose certificate Deplo no longer trusts, and one with Docker down are all skipped before anything is shipped to them, rather than dialed and failed.

The Deplo host is a fallback out of the box - it is the one machine every install has. Any other server can join the pool: open it in Settings -> Servers, then Advanced -> Build as a fallback. The same architecture rule applies, so a fallback that cannot produce a runnable image is skipped rather than tried.

To take a host out of the pool, turn the same switch off. To stop one app from ever building anywhere else, turn off Build somewhere else if that server is down in that app's build settings: its deploy then fails instead, and the running version is left alone.

Configure a build serverCopy Anchor Link

Important limitsCopy Anchor Link

• Both machines need the same CPU architecture. An arm64 builder cannot produce an amd64 image. Mismatched choices are shown but disabled.
• A Compose app cannot use one. There is no single image to build and move.
• The image crosses the network twice, once to the control plane and once out again. Cheap on a fast local network, can cost more than it saves over a slow link.
• The build cache lives on the builder. Moving an app to a different builder starts cold.
• A build-only server is not a deploy target, and never will be.

TroubleshootingCopy Anchor Link

• The builder does not appear in the list - it is not in the Build only role, or its architecture does not match the target.
• Builds happen on another host - the builder was unreachable and the fallback did its job. The deploy log names the host that took over; check the builder's health.
• Deploys queue behind each other - they share the builder's concurrency. Raise it on that server's Overview tab if the machine can take it.

More in Deploys and builds troubleshooting.

See alsoCopy Anchor Link