Gradle build cache with Docker Compose

Run a shared Gradle build cache for your team in one Compose file, with a password and a size limit. This is the shape we suggest once you go past a first trial.

Try it first, on one machine

docker run -d -p 127.0.0.1:8080:8080 -v fscache-data:/home/nonroot ghcr.io/fosterstack/cache:latest

The 127.0.0.1: keeps it reachable from this machine only. A bare -p 8080:8080 opens the port to every network interface, and on a cloud host that is a cache anyone can write to the moment the command returns. Pin a version tag instead of latest for anything real.

The Compose file

This one is open to your CI runners, so it has a password on purpose. A cache that untrusted people can write to can feed files into your builds.

services:
  fscache:
    image: ghcr.io/fosterstack/cache:latest   # pin a version tag
    restart: unless-stopped
    ports:
      - "8080:8080"                    # all interfaces, so auth is on
    volumes:
      - fscache-data:/home/nonroot
    environment:
      FSCACHE_MAX_BYTES: "53687091200"   # 50 GiB, size to your CI volume
      FSCACHE_USERNAME: gradle
      FSCACHE_PASSWORD: change-me        # generate one: openssl rand -base64 24

volumes:
  fscache-data:

• The data volume mounts at /home/nonroot, not /data. The server runs as a non-root user.
• FSCACHE_MAX_BYTES is in bytes. 50 GiB is 53687091200. See server sizing for more values.
• Put an HTTPS proxy in front for real use. Gradle sends the password with every request.

Check it works, with no Gradle project

curl -s localhost:8080/healthz                                   # ok
curl -s -X PUT --data-binary 'hello' localhost:8080/testkey123   # 201
curl -s localhost:8080/testkey123                                # hello

Add -u gradle:your-password to those calls once you have set a password.

Point Gradle at it

Use the settings from our Gradle and Maven setup page, and turn caching on with org.gradle.caching=true. If nothing comes from the cache, work through Gradle remote build cache not working.

Health checks

The container image has no shell, so there is no health check inside the Compose file. Probe /healthz from outside: your orchestrator's HTTP check, a monitor, or curl -f http://localhost:8080/healthz from the host.

Full detail: Docker deploy guide.