Build servers
BetaBuild the image on a dedicated host and ship it to the server that will run it.
Beta
This feature is currently beta/experimental and subject to change. It is not recommended for production. Try it out and share your feedback on our GitHub.
What it is
Use it when builds are starving production of CPU, or when several small servers would rather share one big builder.
How it works
A build server is a server installed in the Build only role: it gets Docker and the address-pool setup, because it runs the full build pipeline, but no Traefik, and it drops out of every deploy-target picker. Nothing is ever routed to it.
At deploy time the builder produces the image, and the image is relayed to the target host through the control plane, because agents cannot dial each other. The deploy occupies a slot in the builder's queue, since that is where the cost is.
Build logs still belong to the app. Read them where you always do.
When the builder is down
A deploy still ships. Deplo tries, in order:
- The app's build server.
- Every server marked Build as a fallback, the Deplo host first.
- 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.
Set one up
Open build settings
Open the app, then Settings -> Deployments -> Advanced settings.
Set where it builds
- Automatic lets Deplo choose
- This app's own server
- A named build server
Keep the fallback on
So a build still happens if the builder is unreachable - on the Deplo host, or on any server you marked as a fallback.
Limits and gotchas
- Both machines need the same CPU architecture. An
arm64builder cannot produce anamd64image. 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.
If it does not work
- 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 in that server's Overview if the machine can take it.
More in Deploys and builds troubleshooting.
See also
Did this page help you?