Getting Started

Getting Started

Deploy the GitHub Actions Cache Server using Docker and use it with self-hosted runners

The cache server comes as a Docker image and can be deployed using Docker Compose or Kubernetes.

1. Deploying the Cache Server

docker-compose.yml
version: '3.9'

services:
  cache-server:
    image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
    ports:
      - '3000:3000'
    environment:
      API_BASE_URL: http://localhost:3000
    volumes:
      - cache-data:/app/.data

volumes:
  cache-data:

Environment Variables

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.

ENABLE_DIRECT_DOWNLOADS

  • Default: false

If set to true, will send a signed URL to the runner. The runner can then download the cache directly from the storage provider. This is useful if you have a large cache and don't want to proxy the download through the cache server.

The actions runner needs to be able to reach the storage provider directly to use direct downloads.

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

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_RESULTS_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, making sure to include a trailing slash.

For example, if your cache server's API_BASE_URL is http://localhost:3000, you would set ACTIONS_RESULTS_URL to http://localhost:3000/.

Make sure to add a trailing slash to the ACTIONS_RESULTS_URL environment variable.

Getting the Actions Runner to Use the Cache Server

The default self-hosted runner overwrites the ACTIONS_RESULTS_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:

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\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\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\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\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\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\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\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /path_to_your_runner/bin/Runner.Worker.dll

This will replace the strings ACTIONS_RESULTS_URL with ACTIONS_RESULTS_ORL in the runner binary. This will prevent the runner from overwriting the ACTIONS_RESULTS_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.


Copyright © 2024