Getting Started
The cache server comes as a Docker image and can be deployed using Docker Compose or Kubernetes.
1. Deploying the Cache Server
version: '3.9'
services:
cache-server:
image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
ports:
- '3000:3000'
environment:
URL_ACCESS_TOKEN: random_token
API_BASE_URL: http://localhost:3000
volumes:
- cache-data:/app/.data
volumes:
cache-data:
Environment Variables
URL_ACCESS_TOKEN
This token is used to authenticate runtime requests to the cache server. It should be a long random string. It is part of the URL used to access the cache server because we cannot use cookies or headers for authentication.
API_BASE_URL
- Example:
http://localhost:3000
The base URL of your cache server. This needs to be accessible by your runners as it is used for making API requests and downloading cached files.
STORAGE_DRIVER
- Default:
filesystem
The storage driver to use for storing cache data. For more information, see Storage Drivers.
DB_DRIVER
- Default
sqlite
The database driver to use for storing cache metadata. For more information, see Database Drivers.
CLEANUP_OLDER_THAN_DAYS
- Default:
90
The number of days to keep stale cache data and metadata before deleting it. Set to 0
to disable cache cleanup.
NITRO_PORT
- Default:
3000
TEMP_DIR
- Default:
/tmp
The directory to use for temporary files (like cache upload buffers).
The port the server should listen on.
2. Setup with Self-Hosted Runners
To leverage the GitHub Actions Cache Server with your self-hosted runners, you'll need to configure a couple of environment variables on your runners. This ensures that your runners can authenticate with and utilize the cache server effectively.
Configuring Environment Variables on Self-Hosted Runners
ACTIONS_CACHE_URL
: This tells your self-hosted runner where to send cache requests. Set this environment variable to the API_BASE_URL
of your cache server with the URL_ACCESS_TOKEN
as first path parameter, making sure to include a trailing slash.
For example, if your cache server's API_BASE_URL
is http://localhost:3000
and your URL_ACCESS_TOKEN
is random_token
, you would set ACTIONS_CACHE_URL
to http://localhost:3000/random_token/
.
Getting the Actions Runner to Use the Cache Server
The default self-hosted runner overwrites the ACTIONS_CACHE_URL
environment variable with the GitHub-hosted cache server URL. To get the runner to use your self-hosted cache server, you'll need to modify the runner binary:
Docker
Just add the following lines to your Dockerfile:
FROM ghcr.io/actions/actions-runner:latest
# modify actions runner binaries to allow custom cache server implementation
RUN sed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x43\x00\x41\x00\x43\x00\x48\x00\x45\x00\x5F\x00\x55\x00\x52\x00\x4C\x00/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x43\x00\x41\x00\x43\x00\x48\x00\x45\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /home/runner/bin/Runner.Worker.dll
Bare Metal
sed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x43\x00\x41\x00\x43\x00\x48\x00\x45\x00\x5F\x00\x55\x00\x52\x00\x4C\x00/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x43\x00\x41\x00\x43\x00\x48\x00\x45\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /path_to_your_runner/bin/Runner.Worker.dll
This will replace the strings ACTIONS_CACHE_URL
with ACTIONS_CACHE_ORL
in the runner binary. This will prevent the runner from overwriting the ACTIONS_CACHE_URL
environment variable and allow it to use your self-hosted cache server.
Doing it this way is a bit of a hack, but it's easier than compiling your own runner binary from source and works great.
3. Using the Cache Server
There is no need to change any of your workflows! 🔥
If you've set up your self-hosted runners correctly, they will automatically use the cache server for caching.