Build servers
A build server builds application images on a separate machine. The completed image is pushed to a container registry, then the deployment server pulls and runs it.
By default, Coolify builds an application on the same server where the application will be deployed. Add a build server when builds use too much CPU, memory, or disk space on the deployment server.
Server roles
Set Server role in the server's General settings:
| Role | Behavior | API value |
|---|---|---|
| Deployments only | Runs resources; images must be built elsewhere. Applications need a Docker image name. | deployment |
| Builds only | Builds images for other servers; cannot host resource deployments. Required for GitHub Actions runners. | build |
| Deployments and builds | Builds images and runs resources on this server. | both |
The API uses server_role. The deprecated is_build_server field remains compatible, but use server_role for new integrations.
Under Team, configure Build server fallback to choose whether builds may fall back to a deployment server when no build server is usable. The server must have a role that allows builds. Disable fallback if builds must stay off deployment machines.
What you need
Before you start, make sure you have:
- a fresh remote server that is not running applications, databases, or services
- Docker Engine on the build server, or permission for Coolify to install it
- a container registry where Coolify can push the completed image
- the registry repository for the application, such as
ghcr.io/example/my-app - access to the application's source repository
The build server should use the same CPU architecture as the deployment server.
A server marked as a build server cannot be selected as a deployment destination. Do not enable this setting on a server that runs applications, databases, or services.
Configure a build server
Choose whether you are adding a new server or using a server that is already connected to Coolify.
Prepare the SSH key
Complete Create and authorize an SSH key before opening the server form.
Open the Servers page
- Open the Coolify dashboard.
- Select Servers in the sidebar.
- Select New server.
- Select IP address or domain.
Add the build server
- Enter the server name, IP address or domain, SSH port, user, and private key.
- Expand Advanced settings and set Server role to Builds only.
- Select Continue.
Coolify adds the server and opens its General page.
Validate the build server
- Select Validate connection.
- Keep the page open while Coolify validates the SSH connection and prepares Docker.
- Wait for the page to show Server is reachable and validated.
When more than one usable build server is available, Coolify selects one at random for each build.
Build servers can also run the GitHub Actions workflow jobs of your organization. Refer to GitHub Actions runners.
Sign in to the container registry
Use Servers > [server] > Registries to log in on the build server and deployment server. See Registry login for presets and credential updates. The SSH procedure below remains available.
Connect to the build server
Connect with the same SSH user configured on the server's General page:
ssh <user>@<build-server-ip>Replace <user> and <build-server-ip> with the values used by your server.
If the server uses an SSH port other than 22, run:
ssh -p <ssh-port> <user>@<build-server-ip>Log in to the registry
docker login <registry-domain>Replace <registry-domain> with the registry hostname, such as ghcr.io. Enter the registry username and access token when prompted.
The login creates ~/.docker/config.json for the current SSH user. Coolify requires this file on the build server.
If the registry repository is private, log in to the registry on the deployment server as well so it can pull the completed image.
Configure an application to use the build server
Open the application General page
- Open Projects in the Coolify sidebar.
- Select the project and environment.
- Select the application that should use the build server.
- Open General.
Enter the Docker image
Enter the full registry repository in Docker Image, for example ghcr.io/example/my-app.
Select Save after entering the image. Coolify cannot deploy with a build server until Docker Image is set.
Enable the build server
- Find Use a Build Server?.
- Enable the setting.
The setting saves immediately. It is not available for Docker Compose applications.
Deploy the application
Start a new deployment and open the deployment logs.
When Coolify selects a build server, the log shows:
Found a suitable build server (<server-name>).Wait for the deployment to finish, then confirm:
- the completed image appears in the container registry
- the application runs on its deployment server
- the application opens from its configured domain
If no usable build server is available, Coolify builds on the deployment server only when the team enables Build server fallback and that server permits builds. A Deployments only server never builds images itself.