HTTP storage

Ccache 4.4+ has support for using HTTP to communicate with a server for the purpose of sharing cache results with others. This page contains hints on how to set up such a server for use with ccache.

In general, ccache will use the HEAD and GET HTTP verbs to read from the cache server. To optionally also update cache entries, ccache will use the PUT verb, and furthermore, ccache may use the DELETE verb. Thus, any simple HTTP server can be used read-only by ccache, while read-write usage requires the further verbs usually provided by, e.g., WebDAV servers. Note that ccache will not explicitly create non-existent directories via MKCOL or the like, so you may need to precreate any needed directories on the server if it cannot be configured to automatically create them (see the NGINX configuration below).

Note that ccache does not directly support HTTPS, but this can be worked around via a local reverse proxy as detailed on the bottom of this page.

See the remote storage backends section in the ccache manual for details on how to configure ccache. See also the Wiki page on Redis storage.

NGINX

NGINX is an open source web server that can be used as a simple remote ccache storage:

1. Add something similar to this to the server part of the configuration:

   location /cache/ {
     # Where to store cache files (must exist with proper file permissions already):
     alias /path/to/cache/directory/;
   
     # Don't log 404 Not Found replies as errors.
     log_not_found off;
   
     # Enable needed HTTP methods:
     dav_methods PUT DELETE;
   
     # Allow creating subdirectories:
     create_full_put_path on;
   
     # Allow individual cache entries to be up to 100 MiB:
     client_max_body_size 100M;
   }

   To require authentication to write, create an htpasswd file and add something like this to the location block:

   # Allow all to read:
   dav_access user:rw group:rw all:r;
   # Allow specific users to write:
   limit_except GET HEAD {
     auth_basic "Ccache remote storage";
     auth_basic_user_file /path/to/htpasswd;
   }

2. Add remote_storage = http://YOUR_SERVER/cache/ to your ccache configuration (or set CCACHE_REMOTE_STORAGE=http://YOUR_SERVER/cache/ if you're using environment variables).

NOTE: Depending on how NGINX is built on your system, you may need to install the ngx_http_dav_module module as well.

A downside with this setup is that it has no automatic cleanup of obsolete cache entries. You can however set up periodic cleanup yourself by running ccache with the --trim-dir option, e.g. via cron.

bazel-remote

bazel-remote is an open source server that is intended to be used as a remote build cache for Bazel, but it can be configured to work as a remote ccache storage as well:

1. Start bazel-remote with something like --dir /path/to/cache/directory --max_size 10 --disable_http_ac_validation. --disable_http_ac_validation is important since that tells bazel-remote to accept any entry values in the /ac/ (action cache) part.
2. Add remote_storage = http://YOUR_SERVER:8080|layout=bazel to your ccache configuration (or set CCACHE_REMOTE_STORAGE='http://YOUR_SERVER:8080|layout=bazel' if you're using environment variables).

This setup gives you automatic LRU cleanup of entries.

NOTE: Using --disable_http_ac_validation for storing arbitrary data in the Bazel cache is a bit of a hack. Make sure that the server administrator thinks that it is OK to sneak ccache entries into the Bazel cache that way. There is no risk of collision, though, since ccache entries will never have the same key as action cache entries.

Apache

TODO: https://httpd.apache.org

NOTE: Need mod_dav

lighttpd

TODO: https://www.lighttpd.net

NOTE: Need lighttpd-mod-webdav

OpenLiteSpeed

TODO: https://openlitespeed.org

NOTE: No native WebDav module?

Google Cloud Storage (GCS)

To use Google Cloud Storage, set the bearer-token attribute for the backend.

TODO: Add example.

HTTPS servers

While ccache does not directly support HTTPS, this can be worked around via a local reverse proxy.

A simple example is mitmproxy (which is here only used as system-independent tool to wrap HTTPS traffic, not for actually monitoring traffic), while basically any reverse proxy that supports the HTTP verbs used by ccache will work.

Here is how you could use mitmproxy:

$ mitmdump --mode reverse:https://my-ccache-http-server.com@44443 &
$ export CCACHE_REMOTE_STORAGE=http://127.0.0.1:44443
# now do your build as usual

Note that by default mitmdump will log any requests to the console, which might be useful for debugging whether the reverse proxy is actually used and works. This can be turned off with --set flow_detail 0.

Arbitrary backends

You can also write a simple HTTP server that supports HEAD and GET (and optionally PUT and DELETE) to adapt arbitrary backends for usage with ccache. Note that the server should optimally be running in the background for the whole time of a ccache-enabled build. See also this comment on issue #1214 for more information on alternative backends.