This manual covers the installation and operation of Gradle Enterprise. It is useful for administrators and maintainers of Gradle Enterprise installations, and build engineers that maintain or develop Gradle builds that leverage Gradle Enterprise.

Installation and operation

Gradle Enterprise leverages Replicated for installation, configuration and software updates. Replicated orchestrates downloading and installing the Gradle Enterprise application on the host machine as well as checking for periodic updates.

Replicated, as well as the Gradle Enterprise application both run on the host in the form of Docker containers. Management of these containers is done transparently by Replicated, however regular Docker commands can be used to inspect the status of running containers.

While the regular docker commands can be used to manage Gradle Enterprise application containers, it is highly recommended that maintenance actions such as starting and stopping the application be done via the Replicated admin console.

Before you install

This section outlines the installation resource requirements and configuration aspects that need to be resolved during installation.

Supported operating systems

Server versions of the following Linux distributions are supported:

  • Debian 7.7+

  • Ubuntu 14.04 / 15.10 / 16.04

  • Fedora 21 / 22

  • Red Hat Enterprise Linux 6.5+

  • CentOS 6+

  • Amazon AMI 2014.03 / 2014.09 / 2015.03 / 2015.09 / 2016.03 / 2016.09 / 2017.03

  • Oracle Linux 6.5+

  • SUSE Enterprise Linux 12

The host machine must support docker-engine (1.7.1+) which requires a 64-bit distribution with a kernel minimum of 3.10. For detailed requirements and installation guides see the docker installation docs.

Installing on non-Linux systems

Gradle Enterprise requires a modern Linux operating system with Docker support. For trial and evaluation purposes, you can use a virtual machine to perform the installation on a non-Linux system. Several desktop virtual machine providers, such as VirtualBox, exist for this purpose.

Virtualized installation considerations

Some considerations when using virtualization in conjunction with Gradle Enterprise are:

  • Any of the above listed Linux distributions will still work, even in a virtualized environment.

  • You will need to forward the necessary ports to the host machine in order to configure Gradle Enterprise and access the application.

    Newer versions of MacOS may have built-in services listening on these ports, in particular, port 8800. If you encounter errors binding to these ports you may need to forward them to a different port on your host.
  • When using a virtual machine provider such as VirtualBox, the IP of your virtualized environment will differ depending on how you have configured networking for the virtual machine. For example, with VirtualBox, if you have set it up with the default networking mode (NAT), then the IP address of the Gradle Enterprise installation will be the same as that of your host machine.

When running in NAT networking mode, a VirtualBox machine will not be able to communicate with a service running on the host machine. This has the implication that a virtualized Gradle Enterprise installation will not be able to communicate with a remote build cache node running on the same machine as the VirtualBox instance. For this, you will need to investigate a different network mode (such as Host-only), or you will need to install the build cache node on a different machine within your organization.
  • If you remap the ports 80 or 443 of your virtual machine, you will need to ensure that the Gradle Enterprise ports are reconfigured to match in the network settings configuration screen. Failing to do this will cause some areas of the Gradle Enterprise UI to go to an incorrect address, and the server will generate an incorrect URL for build scans.

  • Gradle Enterprise can consume a considerable amount of disk space depending on how actively it is used. Keep this in mind when provisioning a virtual disk. Also, depending on the virtualization method used, disk performance may not be consistent with native disk access so Gradle Enterprise performance is likely to be affected.

Using desktop virtualization software such as VirtualBox or Vagrant is not recommended for production deployments.

Storage requirements


Gradle Enterprise stores the majority of its data in the /opt/gradle directory. As Gradle Enterprise collects detailed records of builds (as build scans), considerable amounts of data may be stored in this directory. The amount is determined by how many build scans are being collected and the size of the builds.

The recommended minimum initial capacity to provide is 250 GB. The admin console indicates the space used by /opt/gradle for the last 7 days. When starting with Gradle Enterprise, this should be actively monitored in order to determine your data growth rate.

The following are additional disk capacity requirements:



1 GB


30 GB


250 MB (or 50% of /opt/gradle capacity if backups are enabled)


Disk performance has a significant impact on Gradle Enterprise. For production workloads, storage volumes should exhibit SSD-class disk performance of at least 3000 input/output operations per second (IOPS). Most desktop-class, non-SSD disk drives do not provide this level of performance.

You can run the following benchmark to estimate your disk performance:

docker run --rm -v /opt/gradle/fs-test:/var/lib/postgresql/data postgres pg_test_fsync

The majority of reported results should indicate greater than 3000 ops/sec.

Amazon Web Services

If you are using Amazon Web Services (AWS) and Elastic Block Storage (EBS) to host your Gradle Enterprise instance you should ensure that you provision 3000 or more IOPS for the data volume. Keep in mind that general purpose (or gp2) volumes are limited to 3 IOPS per gigabyte, meaning that 200 GB volume will only provide a maximum of 600 IOPS. If you are provisioning a volume smaller than 2TB you should consider using a provisioned IOPS (or io1) volume.

The recommendations above are based on average workloads. For projects with more complex builds or teams that produce a large number of build scans, Gradle Enterprise may require higher I/O performance than suggested.

CPU & memory requirements

  • Quad-core 2GHz or better CPU

  • 8 GB free RAM

Networking configuration

The following TCP ports on the host system are used by the application:

Port Interface Required Description




Replicated Operator




System admin console




Graphite console



When SSL is enabled (default)

HTTPS port used to access the application



When SSL is disabled

HTTP port used to access the application




Build scans and build cache servers




PostgreSQL database

Firewall and proxy configuration

In addition to the ports listed above the host machine will also need access to the internet for retrieving application images, syncing license information, etc. Depending on your firewall or proxy configuration you may need to whitelist individual websites. Please refer to this document for detailed information on all external websites necessary for installation and proper system function.

If external network access is not possible you can still install Gradle Enterprise via an airgapped installation.

Application hostname

When installing Gradle Enterprise, you will be asked to provide a hostname. This should be the hostname that users of the installation use to access it and therefore should resolve within your network.

This value can be changed later.

If you are unsure what name to assign, or you do not yet have a hostname assigned, you can use the public IP address of the server, or localhost if you only intend to access the installation from the same machine for the time being.

The public IP address is the IP address you would use to SSH on to the machine.

SSL certificate

It is strongly recommended that production installations of Gradle Enterprise are configured to use HTTPS, with a trusted certificate. This requires ownership of a certificate for the public hostname you intend to use that was issued by a trusted certificate authority.

If you do not have a certificate to use you may either:

  1. Allow Gradle Enterprise to generate an untrusted, self-signed, certificate

  2. Disable HTTPS and use plain HTTP

Using an untrusted certificate requires extra build script configuration for both build scans and the build cache, in addition to requiring users to accept the untrusted connection in their browser each time they access the application. However, your data will be encrypted whilst in transit on the network.

Using plain HTTP means that no extra build or browser configuration is required, but your data will not be encrypted while in transit on the network.

Whilst it is possible to run Gradle Enterprise unsecured over HTTP, the Replicated admin console must be run over HTTPS.

For trial installations, using plain HTTP is generally OK and preferable to using a self-signed certificate. It is strongly discouraged for production installations however.


Gradle Enterprise supports multiple installation mechanisms.

Standard installation is recommended as it is simple and requires few steps. It requires the host system to have Internet access.

Once installed, Gradle Enterprise does not require a connection to the Internet. It is possible to only establish an Internet connection for the host system for the initial install and to obtain subsequent updates manually.

Airgapped installation can be performed on a host without an Internet connection. Installation materials are downloaded from a system with Internet access and then manually transferred to the host system.

Some non-essential Gradle Enterprise functions may not be available when operating without an Internet connection.

Airgapped installations are not available for trial licenses.


Installing the admin console
  1. During installation you will be asked for any required proxy settings. You should have this information on hand before proceeding with the next step. Later you may also be prompted to supply the host’s public IP address if the installer was unable to automatically detect it. If this happens, the IP address should be left blank.

    If you intend to run the Gradle Enterprise application with SSL enabled (which is recommended) you should also have the public certificate and private key available prior to beginning installation.

  2. Install Replicated on the target host by issuing the following command on the host machine.

    curl -sSL | sudo bash
    As part of the installation procedure, Replicated will create a user replicated (if one doesn’t exist already), and add it to the docker group of users.
  3. Open a web browser and navigate to https://«hostname»:8800 to access the admin console.

  4. Enter a valid Hostname used by the admin console. This name should be routable on your network and resolve to the IP address of the host machine. It will be used when generating self-signed certificates for the admin console.

  5. For SSL used by the admin console you can either use self-signed certificates or provide your own.

    1. To use self-signed certificates simply select Use Self-Signed Cert.

    2. To provide your own certificates provide files for Private Key and Certificate and select Upload & Continue.

    install ssl 2017.7
    These settings can always be changed later via the Console Settings screen, accessible under the install gear icon icon in the upper-right corner of the admin console.
  6. Select Choose License and navigate to the location of the license file which was sent to you via email.

    install license 2017.7
  7. Choose a method for securing the admin console. Either Anonymous, Password, or LDAP, and select Continue.

    install password 2017.7
    Should you choose to change these settings later, you can do so by visiting https://«hostname»:8800/create-password.
  8. The system will perform some pre-flight checks to test the host system for compatibility. Although the software can be installed without passing these checks it is highly recommended that any deficiencies be addressed. Proper system functionality cannot be guaranteed if the host system does not meet the required criteria.

    install preflight check 2017.7

    Select Continue.

Installing Gradle Enterprise
  1. After installing the admin console the application will begin downloading in the background. When the download is complete installation will begin automatically. At any time you can select Dashboard from the navigation menu to see the current status of the application.

    You will be presented with a screen to allow you to customize various application settings. Changes to these settings can be made at any time. Changes will only take effect after selecting Save on the bottom of the Settings page.

    Selecting Save will require the application to restart for changes to take effect. Select Restart Now to restart the application and apply the new settings. If the application is in the process of starting (during intial installation) then changes will be applied when the application finishes starting. Changes to a stopped application will apply the next time the application is started.

    Enter a valid Hostname. By default this will be the same hostname used by the admin console.

    install hostname 2017.7
    Network Settings

    You can customize SSL settings. By default SSL for the Gradle Enterprise application is enabled and configured to use the same settings as the admin console. You can disable SSL entirely for the application (SSL will still be used for the admin console) by unchecking the box labeled Enable SSL.

    Disabling SSL is not recommended in a production environment, or a testing environment where sensitive data might be exchanged. All information will be transmitted in clear text.

    If you want to use a different certificate and private key than the admin console uncheck the box labeled Use same management console TLS cert/key and provide your own files for SSL Private Key and SSL Certificate.

    If you choose not to provide your own key and certificate, a self-signed certificate will be generated for you.

    The build scan plugin is not configured, by default, to allow publishing to an SSL endpoint using self-signed certificates. If you choose to use self-signed certificates for the application, you will need to explicitly configure the build JVM with an appropriate truststore or disable certificate verification.

    The application defaults to using TCP ports 80 and 443 to host the application. You can override these ports by updating the boxes labeled HTTP Port and HTTPS Port.

    install network settings 2017.7

    The database is persisted to a directory located on the host machine. By default this directory is named /opt/gradle/data/postgresql/data. If you would like the database data to be located elsewhere, update this location appropriately.

    Updating this value is non-destructive. The old data directory will continue to remain on the host system. The application will simply provision a new database at the new location. However, the old data will no longer be available in the application and migration is currently not supported.
    install database 2017.7

    Application logs are persisted to a directory located on the host machine. By default this directory is named /opt/gradle/data/logs. If you would like logs to be located elsewhere, update this location appropriately.

    install logging 2017.7
    Build Scans

    You can optionally provide a set of credentials used to secure viewing of build scans. This only limits attempts to view build scans, publishing of build scans is unaffected.

    install build scans
    Build Cache

    Artifacts stored by the Gradle Build Cache are persisted to a directory located on the host machine. By default this directory is named /opt/gradle/data/buildcache. If you would like these artifacts to be located elsewhere, update this location appropriately.

    You can optionally provide a set of credentials used to secure the UI used to administer the build cache. These pages are located at https://«hostname»/cache-admin.

    install build cache 2017.7

    Gradle Enterprise help and feedback page can optionally provide contact information to users that encounter issues using the system. You can specify the contact name and email address to be displayed on this page.

    install administrator 2017.7
    Do not forget to select Save after changing any of the settings above. Otherwise your changes will not take effect. See this note for details.
  2. Select Dashboard from the navigation menu to see the current status of the application. You should see a screen like the one below once the application has completed installation and the server has successfully started. In the event of an error see the Troubleshooting section for more information.

    install dashboard 2017.7
  3. You should now be able to navigate to application by clicking install open.

Be sure to check the Upgrade notes section for any special considerations when upgrading from older versions of Gradle Enterprise.
  1. Open a web browser and navigate to https://«hostname»:8800 to access the admin console.

  2. Checks for updates are done periodically. When an update is available you will see something similar to the screen below. You can explicitly check for updates at any time by selecting Check Now.

    update dashboard 2017.7
  3. Select View Update.

  4. On the Release History screen select Install Update to install the latest released version.

    Updating requires the application to be temporarily shutdown. This means the application will not be accessible and information for builds run during this downtime period will not be captured.
    update install 2017.7
  5. The updated application images will be downloaded and installation will begin immediately once the download has completed.

  6. Select Dashboard from the navigation menu. The status Started will be shown when installation is complete and the application is up and running.

    update started 2017.7
After upgrading, Docker may keep older Gradle Enterprise images on disk. These unused images can consume a significant amount of disk space. You can clear up space taken by unused Docker images at any time by running the following command:

docker images --filter dangling=true -q | xargs docker rmi



In an airgapped installation, you will need to first install Docker on the host machine, since the automated installer will not install it for you. You can refer to this guide for information about installing Docker in an airgapped fashion. After a compatible version of Docker is installed, follow the instructions below.

  1. Along with your provided license file you will be given a link and password to access the Gradle Enterprise airgap bundle download page.

  2. Select Get Download Link and download the airgap bundle.

    If using wget to download the airgap bundle you will need to use the --trust-server-names option or rename the downloaded file to .airgap. You may also need to surround the URL with quotes (").
  3. Transfer the airgap bundle to the host machine.

  4. Download the admin console installer from

  5. Transfer the installer bundle to the host machine.

  6. Run the admin console installer.

    tar xzvf replicated.tar.gz
    cat ./ | sudo bash -s airgap
  7. Open a web browser and navigate to https://«hostname»:8800 to access the admin console.

  8. Enter a valid Hostname used by the admin console. This name should be routable on your network and resolve to the IP address of the host machine. It will be used when generating self-signed certificates for the admin console.

  9. For SSL used by the admin console you can either use self-signed certificates or provide your own.

    1. To use self-signed certificates simply select Use Self-Signed Cert.

    2. To provide your own certificates provide files for Private Key and Certificate and select Upload & Continue.

    install ssl airgap 2017.7
    These settings can always be changed later via the Console Settings screen, accessible under the install gear icon icon in the upper-right corner of the admin console.
  10. At the following screen, select Choose license and select the license file which was sent to you via email.

    install license airgap 2017.7
  11. Then on the next screen choose Airgapped and click Continue

    install choose installation airgap 2017.7
  12. Enter the location of the .airgap file you downloaded and transferred earlier.

    install airgap package 2017.7
  13. Select Continue.

  14. After the airgap packages have been extracted, choose a method for securing the admin console. Either Anonymous, Password, or LDAP, and select Continue.

    install password 2017.7
    Should you choose to change these settings later, you can do so by visiting https://«hostname»:8800/create-password.
  15. The system will perform some pre-flight checks to test the host system for compatibility. Although the software can be installed without passing these checks it is highly recommended that any deficiencies be addressed. Proper system functionality cannot be guaranteed if the host system does not meet the required criteria.

    install preflight check 2017.7

    Select Continue.

  16. You should then be redirected to the settings screen. You can follow the instructions in the Installing Gradle Enterprise section to customize your installation.

    The application should now be running. You can confirm this by selecting Dashboard from the navigation menu.

  1. Confirm the update path used to search for new airgap bundles. The admin console will look for updates in this folder. You can configure this in the Airgap Settings settings section of the Console Settings page which is accessible via the install gear icon in the navigation menu.

    update airgap 2017.7
  2. Follow steps 1-3 in the Installation section above to get the latest airgap bundle. You will want to place the .airgap file in the location confirmed in the step above.

  3. You can now upgrade the system using the instructions in the Upgrading section.

Backup and disaster recovery

Gradle Enterprise provides system backup and restore capabilities to facilitate disaster recovery. Backups can be triggered manually or scheduled to be done automatically on a periodic basis, and require no system downtime. All system settings, including SSL certificates, as well as all user data is captured in each backup.

Creating snapshots

System backups are termed "snapshots" in the admin console. By default, backup capabilities are enabled but are not scheduled to be done automatically. Snapshots must be either manually triggered or a schedule defined.

Snapshot settings can be configured by clicking on the install gear icon in the upper-right corner of the admin console and selecting Console Settings. Settings are located under the section marked Snapshot & Restore.

Snapshot File Destination

This is the location on the host where snapshots are stored. This directory should be stored off of the host server, either by using a network drive or periodically backing up this directory to another location. This directory will need to be restored to the new host machine during the restore process.

This volume will need to be at least large enough to contain the database data volume size. If database and backup location are sharing the same volume, you will need at least 50% free space to perform a successful backup.
If you are experiencing extended snapshot processing times it is strongly encouraged that you use a different disk for your snapshot volume. Separating IO devices for the database and snapshots volumes will result in significantly better snapshot performance.
Max Number of Snapshots Retained

This is the maximum number of snapshots that will be kept in the snapshot destination directory. Older backups will be removed.

Snapshot Timeout

Snapshot operations can be timed out after an extended period of time. The snapshot process might take some time depending particularly on the size of the database and available IO bandwidth.

Automatic Snapshots

Selecting Enable Automatic Schedule Snapshots allows backups to be created on a scheduled basis.

Unless automatic snapshots are explicitly enabled (disabled by default) you will need to manually trigger snapshots from the admin console Dashboard. Even with automatic snapshots enabled you can manually create a snapshot at any time by selecting Start Snapshot on the Dashboard.
For very large databases snapshots may take an extended amount of time. This is typically reported with the message "Running custom backup script" being displayed on the admin console. You can however inspect the backup logs on the host to determine backup progress. This log is located at /opt/gradle/data/logs/database/backup.log by default. You can also inspect the last 30 days worth of backup logs in the same location.

Restoring from a snapshot

Restoring a snapshot requires a fresh installation of Gradle Enterprise and the Replicated system console. Since snapshots are designed for disaster recovery this will generally be done on a new machine or a fresh OS installation.

Executing the script requires 7zip to be installed on the host system. This can typically be done by installing the p7zip package using your Linux distribution’s package manager.
  1. Restore the backed up snapshots directory to the new host machine.

  2. Perform steps 1-5 of Installing the admin console.

  3. At the screen prompting for a license file select Restore from a snapshot.

  4. You will be presented with a list of available snapshots to restore from. If the snapshot directory from Step 1 is not in the default location enter the location of this folder and select Browse snapshots. Identify the snapshot you wish to restore and select Restore.

    restore snapshot 2017.7
  5. The following screen will display a list of restorable cluster nodes. Since Gradle Enterprise only supports single-node deployments there should only be a single node to restore. Select Restore.

    restore cluster 2017.7
  6. You will be now be redirected to the admin console with all setting restored. Click Dashboard in the navigation menu to check the system status. If the application is running, stop it before continuing with the next step.

  7. Restoring the PostgreSQL database is a manual operation. Execute the following commands on the system host as root.

    /opt/gradle/tools/ \
        /var/lib/replicated/snapshots/postgres/backup.7z # use configured location
  8. Return to the admin console Dashboard and select Start Now.


Issues with the admin console

If you experience difficulty accessing the admin console then you may need to restart the Replicated services on the host machine. To restart Replicated, issue the following commands:

sudo service replicated restart
sudo service replicated-ui restart
sudo service replicated-operator restart
CentOS 7/RHEL 7/Fedora
sudo systemctl restart replicated replicated-ui replicated-operator

Resource usage

Standard Linux process utilities such as ps and top can be used to inspect the resource usage of the application.

Both Replicated and the application run in Docker containers. The following is sample output from running the command ps -aufx which displays the application’s processes.

process list

The admin console (https://«hostname»:8800/dashboard) also displays CPU and memory usage of the application’s Docker containers.

dashboard resource usage 2017.7
Both the Memory Usage and CPU Usage charts have a window of 15 minutes and are representative of the most recent usage data.

Alternatively, docker stats can be used to get more detailed resource usage information about the individual Docker containers.

docker stats


If you are experiencing issues with Gradle Enterprise or the build scan plugin please submit a support ticket at, including details of the issue and an attached Support Bundle.

Support Bundles assist our engineers in troubleshooting your issue by providing the following information about your Gradle Enterprise installation:

  • Host Information

    • Operating System

    • CPU

    • Memory

    • Disk Usage

  • Logs

    • Gradle Enterprise

    • Replicated

  • Docker Configuration

  • Gradle Enterprise Database Statistics

Generating a support bundle

  1. Open a web browser and navigate to https://«hostname»:8800 to access the admin console.

    update dashboard 2017.7
  2. Select Support from the navigation menu.

    support dashboard 2017.7
  3. Click the Download Support Bundle button.

    Generation of the Support Bundle may take several minutes to complete. Once the Support Bundle has been generated it will be automatically downloaded.

Build scans


Creating build scans

Build scans are created from Gradle builds, by using the build scan Gradle plugin. For information on how to use and configure the build scan plugin with your existing Gradle builds, please consult the Build Scan Plugin User Manual.

Viewing build scans

When running a build that publishes build scans, the URL to the build scan for that build is output at the end of the build which looks like this…

Publishing build scan...

To view all of the collected build scans, open the Gradle Enterprise application in your browser. This will redirect you to the /scans page where you can search for build scans. Click on a search result to view the build scan.

usage scan list 2017.7

Plugin version compatibility

Compatibility between versions of Gradle Enterprise and the build scan plugin can be found here.

Build cache

Gradle’s build caching dramatically decreases build times for both local development and continuous integration builds. Build caches store outputs from Gradle tasks and serve them to later Gradle builds to reuse, instead of the outputs being built again.

Gradle Enterprise provides a built-in build cache node as part of each installation, and allows optionally connecting one or more remote nodes. Each node is a cache that can be used by Gradle.

The cache administration service is available at /cache-admin of your Gradle Enterprise installation.

Remote nodes

Remote build cache nodes are installed separately from Gradle Enterprise. They can be used to separate cache artifacts, distribute load, or improve build performance by having a better network link between the build and the node.


The build cache node software is distributed as a Docker image, and is freely available via Docker Hub. Once Docker has been installed, running a build cache node is as simple as the following command:

docker run -d -v /opt/gradle/build-cache-node:/data -p 80:80 gradle/build-cache-node:latest

This will download the latest version of the build cache node container image, create a new container from it, then start it. The cache node will use /opt/gradle/build-cache-node on the host to store its files and serve on port 80. More information about changing these settings can be found below.


The label gradle/build-cache-node:latest identifies the build cache node image with the tag latest. The latest tag always refers to the most recently released version of the build cache node. In order to use a specific version of the image, substitute latest with the version number.

docker run -d -v /opt/gradle/build-cache-node:/data -p 80:80 gradle/build-cache-node:3.1

It is generally desirable to always use the latest version of the build cache node. An exception to this is if your Gradle Enterprise installation is not up to date as each major version of the build cache node has a minimum Gradle Enterprise version requirement.

Gradle Enterprise 2017.8 supports build cache node version 3.x and earlier.

Airgapped installation

In order to install the build cache node on a host that is not connected to the Internet (i.e. airgapped), you will need to first obtain the image on an Internet connected host, then transfer it to the airgapped destination.

  1. On the non-airgapped machine pull down the latest docker image for the node

    docker pull gradle/build-cache-node:latest
  2. Export the image to a file

    docker save gradle/build-cache-node:latest -o build-cache-node.tar
  3. Copy this file across to the airgapped host, and then import the image into docker

    docker load -i build-cache-node.tar

The node can then be started and configured on the airgapped host in the same manner as a non-airgapped install:

docker run -d -v /opt/gradle/build-cache-node:/data -p 80:80 gradle/build-cache-node:latest

Specifying a data directory

The build cache node software stores the cache artifacts and other working files (e.g. config, logs) to disk. Inside the container, these files are written to the /data directory. It is strongly recommended to explicitly mount a directory from the host to this path within the container. If no explicit mount is provided, Docker will provision a persistent host directory for you in a location of its choosing.

When starting the container, the -v switch can be used to specify which directory on the host to mount to /data within the container. The command below demonstrates using the /opt/gradle/build-cache-node directory on the host as the data directory for the build cache node.

docker run -d -v /opt/gradle/build-cache-node:/data -p 80:80 gradle/build-cache-node:latest

Each build cache node must have its own data directory. Sharing a data directory between cache nodes is not supported.

When choosing where to store the cache data (i.e. which host directory to mount to /data within the container), be sure to choose a disk volume that has adequate storage capacity for your desired cache size.

For more information on managing data volumes with Docker, please see this tutorial.

Serving via HTTPS

By default, the remote cache node serves over HTTP. To use HTTPS instead, place your certificate (including intermediates) at «data-dir»/conf/ssl.crt and your private key at «data-dir»/conf/ssl.key. Both files must be in PEM format.

If these files are present when the node starts, it will serve HTTPS connections on port 443 and redirect any plain HTTP requests on port 80 to HTTPS on port 443.

The HTTP to HTTPS redirect will only work correctly if the container’s 443 port is mapped to the host’s 443 port.

Specifying the port mapping

Within the cache node container, HTTP requests are served on port 80 and HTTPS requests are served on port 443, if enabled. These ports must be mapped to ports on the host in order to expose them. It is recommended to map these ports to their equivalents on the host in order to avoid the need to specify the port number when accessing the cache node. This can be done with -p 80:80 for HTTP and -p 443:443 for HTTPS.

To expose the application via different ports, simply use a different number for the preceding number in each -p argument. The following command exposes HTTPS traffic via port 8443 on the host:

docker run -d -v /opt/gradle/build-cache-node:/data -p 8443:443 gradle/build-cache-node:latest

Connecting with Gradle Enterprise

To connect a remote node to your Gradle Enterprise installation, you first need to register it.

Visit /cache-admin of your Gradle Enterprise installation, and select Nodes from the left menu. In the Remote nodes > Create new node section, enter the name for your node and click Create new node.

controller after new node added 2017.7

The node will now be listed in the Existing nodes section. 

Each node is assigned a key and a secret. The node needs to be configured with the key and secret.

The secret is only viewable for 5 minutes after node creation. If the node secret is lost, use the regenerate function to issue a new secret which will then be viewable for 5 minutes.
controller secret 2017.7

Visit / of the remote cache node, expand the Gradle Enterprise section by clicking on Settings, and enter the required configuration.

node setup v3.0

Once a connection is established, the screen will change to indicate a successful connection and show the URL of the dedicated page for configuring/administering the node via the Gradle Enterprise installation.

Securing the cache node UI

You may wish to prevent casual access to the cache node user interface in order to prevent the Gradle Enterprise connection settings being changed. In order to do so, create a file at «data-dir»/conf/credentials.txt with the desired username and password on separate lines, as per the following example:

The container will need to be restarted after creating or changing this file.

Accessing the remote cache node’s configuration page will now require entering this username and password.

Build cache node compatibility

Compatibility between versions of Gradle Enterprise and the build cache node can be found here.

Node configuration

Click the Nodes item in the left menu to access the node listing. Click View built-in node details to administer the built-in node, or click the name of a remote node in the existing nodes table to administer that node.

controller built in details 2017.7


The bandwidth and latency of the network link between a build and a build cache significantly affects build performance. New replication capabilities allow users to use a cache node that they have a better network link to, while reusing artifacts from another cache node that is further away. This is particular effective for geographically distributed teams.

If a cache node receives a request for a cache item it does not have but its replication source does, it will take a copy of it and then serve it. This initial request may not be faster than using the replication source directly, but subsequent requests by all nodes with the given replication source will be faster.

A typical arrangement is to have continuous integration builds push to a cache node on a local network, and have other nodes used by developers in different locations, ideally on their local network, use it as their replication source.

replication network

Replication is one-way (i.e. replication sources do not copy artifacts from nodes using them as a source). Furthermore, a node that is acting as a replication source cannot itself use a replication source.

Replication is not supported with remote nodes earlier than 3.0. This setting will not be shown for such nodes.

Target cache size

When necessary, in order to make space for newly received cache entries, items that have been used least recently will be evicted from the cache. It is strongly recommended to increase this setting from the default setting of 10000 (i.e. 10 gigabytes).

Maximum artifact size

Attempts to store artifacts larger than this limit will be rejected. The default setting of 100 is suitable for most builds and should only need to be increased if your builds produce large outputs.

Cache access control

Access to the build cache can be restricted. You can specify one or more credentials and whether they have Read or Read and Write access. If one or more users have been added, it is possible to specify the access level for anonymous users. Specify None if you don’t want to allow anonymous access. If no credentials are specified, access to the cache is unrestricted.

Refer to the Gradle user guide for details on how to specify credentials to use when accessing a cache.

Versions of the remote node prior to version 3.0 only support a simpler permission model. The controls will be respectively different for such nodes.

Gradle usage

In order to use a build cache, the address of the build cache needs to be configured in your Gradle builds.

The built-in cache node is available via http://«gradle-enterprise-hostname»/cache/ (or with https if configured):

buildCache {
    remote(HttpBuildCache) {
        url = ''

If your Gradle Enterprise installation is using HTTPS with a self-signed or untrusted certificate, connection to the build cache will fail. As of Gradle 4.2, you can allow connections to untrusted servers by adding allowUntrustedServer = true to the configuration:

buildCache {
    remote(HttpBuildCache) {
        url = ''
        allowUntrustedServer = true

Earlier versions of Gradle do not support untrusted HTTPS connections to a build cache.

Remote nodes are available via http://«remote-cache-node-hostname»/cache/ (or with https if configured):

buildCache {
    remote(HttpBuildCache) {
        url = ''

For information about using a build cache from Gradle, please consult the Gradle user manual.

Using multiple caches

When leveraging replication, the build configuration should allowing using the best available cache node. One approach is to set a default cache location, while allowing users to override it for their environment.

This can be done by leveraging system properties:

buildCache {
    remote(HttpBuildCache) {
        url = System.getProperty("buildCacheUrl", "https://cache1/cache/")

Users can then specify their best build cache node by adding the following to their ~/.gradle/ file:


More automatic schemes are also possible, depending on your environment. For example, if you are able to programmatically determine where the build is running, it may be practical to choose the best cache node automatically within the cache configuration logic.

Uninstalling Gradle Enterprise

To uninstall Gradle Enterprise, you first need to follow the steps to uninstall Replicated, which can be found here.

You can then remove the replicated user that was created on install, by running the command:

sudo userdel -r replicated

This will remove the user, along with their home directory.

Appendix A: Upgrade notes

Minor internal database restructuring upgrade downtime

This update includes an internal database restructure that may take a small amount of time. Installations with many 100,000s of build scans and a large build cache may notice an upgrade time of 5 - 30 minutes, depending on their size and performance of server. For most installations, the downtime will be less than 5 minutes.

Default size of build cache has increased

The default maximum cache size of the built-in build cache node, and version 3.2+ of the remote build cache node, has increased from 1GB to 10GB. As a result, disk usage may increase after upgrading. If you have previously changed your cache size from the default, it will not be changed. For more information see the Node configuration section.