Build Server

Build servers allow you to separate the build process from your deployment servers. This is particularly useful when you want to compile your applications on a dedicated server with more resources, or when you want to keep your deployment servers lightweight.

Overview

A Build Server is a remote server dedicated to building and compiling your applications. Instead of building your application on the deployment server, Dokploy will:

1. Connect to the build server
2. Clone your repository and build your application
3. Create a Docker image
4. Push the image to a registry
5. Deploy the image to your deployment server

This approach offers several benefits:

• Resource Optimization: Use powerful build servers without paying for expensive deployment servers
• Security: Keep your source code and build process separate from production
• Flexibility: Build once, deploy to multiple servers
• Performance: Dedicated build resources mean faster builds

Prerequisites

Before setting up a build server, ensure you have:

1. A Dokploy instance running
2. A remote server for builds (VPS, cloud instance, or dedicated server)
3. SSH access to the build server
4. Docker installed on the build server (or use Dokploy's automatic setup)
5. A Docker registry to store your built images (Docker Hub, GitHub Container Registry, etc.)

Setting Up a Build Server

Step 1: Add a New Server

Navigate to Dashboard → Remote Servers → Add Server -> Build Type (Build Server) in your Dokploy dashboard.

Fill in the server details:

• Name: A descriptive name (e.g., "Build Server - EU")
• IP Address: The public IP address of your build server
• Port: SSH port (default is 22)
• Username: SSH username (usually root or your custom user)
• SSH Key: Select the SSH key to use for authentication

Step 2: Setup the Build Server

After creating the server, you need to install Docker and configure it:

1. Click on the server you just created
2. Click on Setup Server ->
3. Follow the setup instructions:
   • Automatic Setup: Copy the command and run it on your server
   • Manual Setup: Follow the step-by-step instructions if automatic setup fails

Step 3: Configure as Build Server

Once you have access to the server, you need to configure it as a build server:

1. Go to the Deployments tab
2. Click on the Setup Server button
3. A modal will appear showing the commands being executed on the server to configure everything necessary
4. Once the setup process finishes, navigate to the Validate tab
5. Verify that all status items show as green, indicating the build server is ready

Using a Build Server

Configure an Application to Use a Build Server

When creating or editing an application:

1. Go to the Advanced tab

2. In the Build Server section:

   • Enable Custom Build Server: Toggle this on
   • Select Build Server: Choose your build server from the dropdown

3. Configure Registry (required for build servers):

   • Go to Settings → Registries
   • Add a Docker registry (Docker Hub, GHCR, etc.)
   • Configure your registry credentials

4. Select Registry in Application:

   • In your application's Advanced tab
   • Under Cluster Settings
   • Select the registry where built images will be pushed

Build Process Flow

When you deploy an application with a custom build server:

1. Build Phase:

   • Dokploy connects to your build server via SSH
   • Clones your repository on the build server
   • Builds the Docker image on the build server
   • Pushes the image to your configured registry

2. Deploy Phase:

   • Dokploy connects to your deployment server(s)
   • Pulls the built image from the registry
   • Deploys the container on your deployment server(s)

Docker Registry Configuration

Build servers require a Docker registry to store built images. For detailed instructions on configuring a registry, see the Docker Registry guide.