Your first 15 minutes with a self-hosted build cache

A checklist from nothing to your first FROM-CACHE. I timed the commands on a real 0.2.1 release: ten seconds in all, on a laptop that already had Gradle and Java and a fast network. The 15 minutes is for you: reading, choosing values, and pointing your own project at the server.

What I timed

The checklist

1. Decide where it will run

• A machine your CI runners and developers can reach. The server is one small program, and disk is what matters. See server sizing.
• Plan on HTTPS for anything beyond a first try. Gradle sends the password with every request.

2. Download it and check it is ours

VER=0.2.1
PLATFORM=darwin_arm64    # or linux_amd64, linux_arm64, darwin_amd64
gh release download v${VER} --repo fosterstack/cache \
  -p checksums.txt -p checksums.txt.bundle -p "fscache_${VER}_${PLATFORM}.tar.gz"
cosign verify-blob --bundle checksums.txt.bundle \
  --certificate-identity-regexp='^https://github.com/fosterstack/cache/' \
  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' checksums.txt
sha256sum -c <(grep "fscache_${VER}_${PLATFORM}.tar.gz" checksums.txt | grep -v sbom)

You should see Verified OK and then ...tar.gz: OK. More checks are in Verify a release yourself. Prefer a container? See Gradle build cache with Docker Compose.

3. Start it with a password and a size cap

tar xzf fscache_${VER}_${PLATFORM}.tar.gz
FSCACHE_USERNAME=gradle FSCACHE_PASSWORD=<a long secret> \
FSCACHE_MAX_BYTES=1073741824 ./fscache

That cap is 1 GiB, in bytes. Real caches are bigger; copy values from the sizing page.

4. Check it is up

• curl localhost:8080/healthz should print ok.
• curl -u gradle:<secret> localhost:8080/statusz should show "version": "v0.2.1".

5. Point Gradle at it

In settings.gradle.kts, and turn caching on with org.gradle.caching=true in gradle.properties:

// FosterStack Cache — remote Gradle build cache.
// https://github.com/fosterstack/cache
buildCache {
    remote<HttpBuildCache> {
        url = uri("http://127.0.0.1:8080/")
        isPush = true
        credentials {
            username = "gradle"
            password = System.getenv("FSCACHE_PASSWORD")
        }
    }
}

Use 127.0.0.1 for a first try on the same machine. On Gradle 9.8.0 the name localhost was refused without an opt-in. Maven instead? See the Maven setup.

6. Build twice and look for FROM-CACHE

export FSCACHE_PASSWORD=<a long secret>
gradle build --build-cache
gradle clean
gradle build --build-cache
> Task :compileJava FROM-CACHE

In my run the first build printed > Task :compileJava and the second > Task :compileJava FROM-CACHE, and the status page showed one entry and one hit. (I had turned Gradle's local cache off in this test, so the hit had to come from the server. With it on, a hit can come from your own machine instead, and the server's hit counter may not move. I did not test that case.) For a fuller walk-through, see the Gradle build cache tutorial. If the second build does not show it, see Gradle remote build cache not working.

7. Before you roll it out to a team

• Put it behind HTTPS and give CI the read-write login and everyone else the read-only one: let CI write, developers only read.
• Watch it: monitoring. Know how it forgets: eviction.
• Know how to empty it: reset, and how to move it: back up and restore.

This is a first try, not a production plan. The project is early, and the paid tiers are not built.