Build servers

Beta

Build 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.

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

A build server has the Build only role: Docker, no Traefik, never a deploy target. It sends the finished image to the target through the control plane, and the deploy takes a slot in the builder's queue. Build logs stay on the app.

Configure a build server

Add a Build only server

Pick the Build tile in Add a server.

Choose where the app builds

Open the app, then Settings -> Advanced -> Build on:

  • Automatic: the least busy online Build only server of the same architecture, oldest first on a tie. With none in the fleet, it builds on the app's own server.
  • The app's own server: always build where it runs.
  • Any other server the team can use, Build only or not. One with a different CPU architecture is listed but disabled.

The choice saves at once and applies on the next deploy. Leave Build somewhere else if that server is down on, see below.

When the builder is down

A deploy still ships. Deplo tries, in order, and the deploy log names the host that built it:

  1. The app's build server.
  2. Every server marked Build as a fallback, the Deplo host first, then the least busy.
  3. The app's own server.

Only online hosts of the same architecture are tried. One that is offline, has Docker down or a certificate Deplo no longer trusts is skipped before anything is shipped to it.

  • The Deplo host is a fallback out of the box. Add or remove any other server with Settings -> Servers -> the server -> Advanced -> Build as a fallback. A Backups only server cannot be one.
  • To make one app fail instead, turn off Build somewhere else if that server is down in its Build on row. The running version is left alone.

Important limits

  • Both machines need the same CPU architecture. An arm64 builder cannot build for an amd64 server.
  • Only apps Deplo builds from source (Git or an upload) can use one. A Docker image has nothing to build, and a Compose app, pasted or from the repository, builds where it runs.
  • The image crosses the network twice: builder to control plane, then out to the target. Cheap on a fast network, can cost more than it saves over a slow link.
  • The build cache lives on the builder. A different builder starts cold.

Troubleshooting

  • The server is not in the Build on list: it is not shared with this team, or it is a Backups only server. Listed but greyed out means a different architecture.
  • Builds happen on another host: the builder was down and the fallback took over. The deploy log names the host; check the builder's health.
  • Deploys queue behind each other: they share the builder's Concurrent deployments. Raise it on that server's Overview tab if the machine can take it.

More in Deploys and builds troubleshooting.

See also

Did this page help you?

On this page