The Gradle build cache node software is a freely available HTTP remote cache server for Gradle’s build caching functionality. This manual covers obtaining, installing and operating one or more build cache nodes.

Use of Gradle’s build cache node software is subject to the Gradle Terms of Service.

Build cache nodes can optionally be connected with Gradle Enterprise for centralized management and monitoring, and to enable replicating cache entries between multiple nodes.

The build cache node is distributed as a Docker image via Docker Hub, and as a executable JAR. Both distributions offer the same functionality.

Requirements

Data directory disk usage

The build cache node requires a single directory, referred to as the “data directory”, to store its cache entries and other files. The default size of the cache is 10 GB. The build cache node will use a few 10s of MB’s more than the cache size to store log files, config files and other operational files.

CPU & memory

By default, the build cache node uses up to about 1.5 GB of memory.

The build cache node does not require significant CPU resources. Performance is generally constrained by network access to the build cache node.

Java runtime

The JAR distribution of the build cache node requires a Java 8 runtime. All other versions are unsupported.

Installation

Docker

Installation

With Docker installed, starting a build cache node is as simple as the following command:

docker run -d -v /opt/build-cache-node:/data -p 80:5071 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/build-cache-node on the host to store its files and serve on port 80. More information about changing these settings can be found in the following sections.

Airgapped installation

In order to install the Docker 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 system, 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/build-cache-node:/data -p 80:5071 gradle/build-cache-node:latest

Versioning

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/build-cache-node:/data -p 80:5071 gradle/build-cache-node:5.0

It is generally desirable to always use the latest version of the build cache node. An exception to this is if you are attaching the node to a Gradle Enterprise installation that is not up to date as each major version of the build cache node has a minimum Gradle Enterprise version requirement. These minimum versions can be found in the Gradle Enterprise compatibility document.

Binding the data directory

The build cache node container uses /data inside the container as the application data directory. When starting the container, the -v switch should be used to specify which directory on the host to mount to this directory in the container.

The command below demonstrates using the /opt/build-cache-node directory on the host as the data directory for the build cache node:

docker run -d -v /opt/build-cache-node:/data -p 80:5071 gradle/build-cache-node:latest
If the container is started without a mount for /data, Docker will create a directory on the host in a location of its choosing to use.

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.

Port mapping

The cache node container exposes a single port 5071. This port must be mapped to a port on the host in order to expose it.

It is recommended to map this port to one of the standard HTTP ports 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:5071 for HTTP and -p 443:5071 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 traffic via port 8443 on the host:

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

Auto start

The build cache node container can be automatically restarted on system boot by leveraging Docker’s restart policies. Starting a build cache node container with --restart always will ensure that it is always running unless explicitly stopped.

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

JAR

You can download version 5.0 of the JAR here.

Older versions of the JAR can be found in the appendix below.

Running

Once you have downloaded the JAR file, it can be run simply with java command:

java -jar build-cache-node-5.0.jar

This will start the node with a data directory inside the $TEMP location and listening on port 5071.

The build cache node JAR requires Java 8. All other Java versions are unsupported.

Specifying a data directory

It is strongly recommended to specify an explicit data directory location with the --data-dir option:

java -jar build-cache-node-5.0.jar --data-dir /opt/build-cache-node

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

To use the current directory as the data directory, use --data-dir .

Specifying the port

The default listening port is 5071.

To use a different port, use the --port option:

java -jar build-cache-node-5.0.jar --data-dir /opt/build-cache-node --port 443
Most systems require super user privileges to bind to a port lower than 1024.

In the absence of a --port option, the PORT environment variable is also respected.

Optimized HTTPS

The build cache node can server HTTPS traffic more efficiently if OpenSSL is installed on the host. If HTTPS is configured but a usable OpenSSL installation cannot be found, the application will emit a warning to the console of:

WARNING: Unable to use optimized HTTPS support as OpenSSL was not found.

Auto start

The build cache node JAR provides no built-in mechanism for auto starting on system restart. This must be implemented with your operating system’s process manager or similar.

The following demonstrates how to use systemd, a popular process manager for Linux systems, to achieve this.

1. Create a file, build-cache-node.sh as root and make it executable, with the following contents:

#!/bin/bash
# Launches Gradle Remote Build Cache node with correct arguments
# Should be run as superuser
java -jar /path/to/build-cache-node-5.0.jar --data-dir /opt/build-cache-node --port 80

2. Create a file, /lib/systemd/system/gradle-remote-build-cache.service as root and make it executable, with the following contents:

[Unit]
Description=Gradle Remote Build Cache
After=network.target
StartLimitIntervalSec=0

[Service]
Restart=always
RestartSec=1
ExecStart=/path/to/build-cache-node-5.0.sh

[Install]
WantedBy=multi-user.target

3. Run the following to start the build cache node for the first time:

systemctl start gradle-remote-build-cache

4. Run the following to have systemd start the build cache node on system boot:

systemctl enable gradle-remote-build-cache

Configuration

The cache settings and Gradle Enterprise connection settings can be configured via the build cache node’s web interface. Since version 4.2, configuration can also be specified by a config file.

Configuring the node via the web interface is generally more convenient, while configuring via the configuration file is generally more appropriate for automated installations.

Editing the file

The config file is stored at «data-dir»/conf/config.yaml, and is in YAML format. It is read at application startup, and is written to when the config is updated via the web interface.

The schema for the config file is versioned. Build cache node version 5.0 uses schema version 1. This schema is published in JSON schema format, and is available here.

The config file should always start with the schema version:

version: 1

The following is an example of a complete config file that may used as a starting point:

version: 1
registration:
    serverAddress: "https://«ge-hostname»"
    nodeAddress: "https://«node-hostname»"
    key: "«key»"
    secret: "«secret»"
cache:
  targetSize: 50000
  maxArtifactSize: 5
  credentials:
    anonymousLevel: "READ"
    users:
      - username: "ci-user"
        password: "password"
        level: "READWRITE"
        note: "Continuous Integration User"
      - username: "developer"
        password: "another"
        level: "READWRITE"
uiAccess:
   username: "admin"
   password: "password"

The various sections will be explained below.

Gradle Enterprise registration

Build cache nodes can be registered and connected with a Gradle Enterprise installation to enable extra features, such as centralized monitoring and cache entry replication. The registration can be configured via the web interface or via the config file.

You must first register the node with Gradle Enterprise in order to obtain a key and secret for the node. Details on this process can be found in the Gradle Enterprise Admin Manual.

The following is an example config file snippet for configuring the Gradle Enterprise registration:

version: 1
registration:
    serverAddress: "https://«ge-hostname»"
    nodeAddress: "https://«node-hostname»"
    key: "«key»"
    secret: "«secret»"

Cache settings

The cache settings determine aspects of the build cache used by Gradle. They can be configured via the web interface or config file.

Target cache size

If adding a new cache entry increases the combined size of all cache entries over the target cache size, the least recently used cache entries will be evicted to make space.

The value is configured in MB, and defaults to 10 GB.

The following is an example config file snippet for changing the target size to 50 GB:

version: 1
cache:
    targetSize: 50000

Maximum artifact size

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

The following is an example config file snippet for changing the maximum artifact size to 200 MB:

version: 1
cache:
    maxArtifactSize: 200

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.

At the top level of the cache section in the config file, you can optionally define a credentials section specifying fine-grained access to the cache. If credentials are not specified, there are no access controls.

The credentials section can contain a list of users with three mandatory fields: username, password and level. The level field may have a value of READ or READWRITE as a string. Users can also have an optional note which is a string to describe the user and aid in administration.

The following is an example config file snippet for configuring two users with read and write access:

version: 1
cache:
  credentials:
    users:
      - username: "ci-user"
        password: "password"
        level: "READWRITE"
        note: "Continuous Integration User"
      - username: "developer"
        password: "another"
        level: "READWRITE"

When any users are defined, anonymous access defaults to being denied. This can be changed by specifying a READ or READWRITE value for the anonymousLevel field.

The following is an example config file snippet for configuring read only anonymous access:

version: 1
cache:
  credentials:
    anonymousLevel: "READ"
    users:
      - username: "ci-user"
        password: "password"
        level: "READWRITE"
        note: "Continuous Integration User"

UI access control

Access to the build cache node’s admin web interface can be restricted via the config file.

The following is an example config file snippet for restricting access to the admin web interface:

version: 1
uiAccess:
  username: "myChosenUsername"
  password: "sdlfjhpos6lnFLRJGFLAE"

Accessing the build cache node’s configuration page will now require entering this username and password. This does not affect access to the actual cache by Gradle.

Prior to v4.2 of the remote cache node, to secure the UI, you can create a file at «data-dir»/conf/credentials.txt with the desired username and password on separate lines, as per the following example:

myChosenUsername
sdlfjhpos6lnFLRJGFLAE

Enabling HTTPS

By default, the build cache node serves over HTTP.

To use HTTPS instead, place your X.509 certificate (including intermediates) at «data-dir»/conf/ssl.crt and your PKCS#1 or PKCS#8 private key at «data-dir»/conf/ssl.key. Both files must be in PEM format.

Using a generated certificate

This feature requires version 4.3 or later of the cache node.

Alternatively, you can have the server generate its own self-signed certificate to use. To do this, specify the --generate-self-signed-cert argument to the node application.

java -jar build-cache-node-4.3.jar --data-dir /opt/build-cache-node --port 443 --generate-self-signed-cert

Or when using the Docker image:

docker run -d -v /opt/build-cache-node:/data -p 80:5071 gradle/build-cache-node:latest --generate-self-signed-cert

This certificate will not be trusted by clients, and will require extra configuration by clients.

The build cache configuration in your Gradle builds will need to indicate that untrusted connections are allowed. This can be done as in the following example:

buildCache {
    remote(HttpBuildCache) {
        url = 'https://my-cache-node.company.com/cache/'
        allowUntrustedServer = true
    }
}
buildCache {
    remote(HttpBuildCache::class) {
        url = uri("https://my-cache-node.company.com/cache/")
        isAllowUntrustedServer = true
    }
}

If you are connecting the cache node with Gradle Enterprise, you will need to configure it to allow untrusted connections with cache nodes. This can be done by enabling this in the Gradle Enterprise admin console.

If you are connecting the node with other cache nodes (i.e. for replication), you will need to configure those nodes to allow untrusted SSL connections, for which how to do so is described in the next section.

Allowing untrusted SSL connections

This feature requires version 4.3 or later of the cache node.

By default, the cache node will not allow connections to Gradle Enterprise or other cache nodes if they serve over HTTPS and present untrusted certificates (e.g. self-signed). In order to allow such connections, the cache node must be started with the --allow-untrusted-ssl argument.

java -jar build-cache-node-4.3.jar --data-dir /opt/build-cache-node --port 443 --allow-untrusted-ssl

Or when using the Docker image:

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

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://«build-cache-node-hostname»/cache/ (or with https if configured):

buildCache {
    remote(HttpBuildCache) {
        url = 'https://gradle-build-cache.mycompany.com/cache/'
    }
}
buildCache {
    remote(HttpBuildCache::class) {
        url = uri("https://gradle-build-cache.mycompany.com/cache/")
    }
}

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

Appendix A: JAR downloads

Appendix B: Config schema downloads