Skip to content

Commit b757bcb

Browse files
LouisHaftmannLouisHaftmann
committed
docs: proxy server setup
1 parent fa66c37 commit b757bcb

File tree

6 files changed

+85
-97
lines changed

6 files changed

+85
-97
lines changed

‎.dockerignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,5 @@ node_modules/
77
data/
88
.env*
99
.eslintcache
10-
test/
10+
test/
11+
certs/

‎README.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,30 @@ This is a drop-in replacement for the official GitHub hosted cache server. It is
1010
- 😎 Easy setup
1111

1212
```yaml
13-
version: '3.9'
14-
1513
services:
1614
cache-server:
17-
image: ghcr.io/falcondev-oss/github-actions-cache-server
15+
image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
1816
ports:
1917
- '3000:3000'
18+
- '8000:8000'
2019
environment:
2120
API_BASE_URL: http://localhost:3000
21+
CA_KEY_PATH: /run/secrets/ca_key
22+
CA_CERT_PATH: /run/secrets/ca_cert
2223
volumes:
2324
- cache-data:/app/.data
25+
secrets:
26+
- ca_key
27+
- ca_cert
2428

2529
volumes:
2630
cache-data:
31+
32+
secrets:
33+
ca_key:
34+
file: ./key.pem
35+
ca_cert:
36+
file: ./cert.pem
2737
```
2838
2939
## Documentation

‎docs/app.config.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ export default defineAppConfig({
3030
],
3131
},
3232
footer: {
33-
credits: 'Copyright © 2024',
33+
credits: 'Made wih ❤️ by @falcondev-oss',
3434
colorMode: false,
3535
links: [
3636
{

‎docs/content/1.getting-started/1.index.md

Lines changed: 53 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,30 @@ The cache server comes as a Docker image and can be deployed using Docker Compos
88
## 1. Deploying the Cache Server
99

1010
```yaml [docker-compose.yml]
11-
version: '3.9'
12-
1311
services:
1412
cache-server:
1513
image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
1614
ports:
1715
- '3000:3000'
16+
- '8000:8000'
1817
environment:
1918
API_BASE_URL: http://localhost:3000
19+
CA_KEY_PATH: /run/secrets/ca_key
20+
CA_CERT_PATH: /run/secrets/ca_cert
2021
volumes:
2122
- cache-data:/app/.data
23+
secrets:
24+
- ca_key
25+
- ca_cert
2226

2327
volumes:
2428
cache-data:
29+
30+
secrets:
31+
ca_key:
32+
file: ./key.pem
33+
ca_cert:
34+
file: ./cert.pem
2535
```
2636
2737
### Environment Variables
@@ -32,6 +42,14 @@ volumes:
3242

3343
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.
3444

45+
#### `CA_KEY_PATH`
46+
47+
Path to the CA key. This is used for proxying https requests. Which is needed for intercepting cache requests.
48+
49+
#### `CA_CERT_PATH`
50+
51+
Path to the CA certificate. This is used for proxying https requests. Which is needed for intercepting cache requests.
52+
3553
#### `STORAGE_DRIVER`
3654

3755
- Default: `filesystem`
@@ -60,74 +78,67 @@ variant: subtle
6078
---
6179
::
6280

63-
#### `CLEANUP_OLDER_THAN_DAYS`
81+
#### `CACHE_CLEANUP_OLDER_THAN_DAYS`
6482

6583
- Default: `90`
6684

6785
The number of days to keep stale cache data and metadata before deleting it. Set to `0` to disable cache cleanup.
6886

69-
#### `NITRO_PORT`
87+
#### `CACHE_CLEANUP_CRON`
7088

71-
- Default: `3000`
89+
- Default: `0 0 * * *`
7290

73-
The port the server should listen on.
91+
The cron schedule for running the cache cleanup job.
7492

75-
## 2. Setup with Self-Hosted Runners
93+
#### `UPLOAD_CLEANUP_CRON`
7694

77-
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.
95+
- Default: `*/10 * * * *`
7896

79-
### Configuring Environment Variables on Self-Hosted Runners
97+
The cron schedule for running the upload cleanup job. This job will delete any dangling (failed or incomplete) uploads.
8098

81-
**`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.
99+
#### `PROXY_PORT`
82100

83-
For example, if your cache server's `API_BASE_URL` is `http://localhost:3000`, you would set `ACTIONS_RESULTS_URL` to `http://localhost:3000/`.
101+
- Default: `8000`
84102

85-
::u-alert
86-
---
87-
icon: 'tabler:alert-triangle'
88-
class: ring-amber-400
89-
color: amber
90-
description: Make sure to add a trailing slash to the ACTIONS_RESULTS_URL environment variable.
91-
variant: subtle
92-
---
93-
::
103+
The port the proxy server should listen on.
94104

95-
### Getting the Actions Runner to Use the Cache Server
105+
#### `NITRO_PORT`
96106

97-
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:
107+
- Default: `3000`
98108

99-
#### Docker
109+
The port the server should listen on.
100110

101-
Just add the following lines to your Dockerfile:
111+
#### `TEMP_DIR`
102112

103-
```dockerfile [Dockerfile]
104-
FROM ghcr.io/actions/actions-runner:latest
113+
- Default: os temp dir
105114

106-
# modify actions runner binaries to allow custom cache server implementation
107-
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
108-
```
115+
The directory to use for temporary files.
109116

110-
#### Bare Metal
117+
## 2. Setup with Self-Hosted Runners
111118

112-
::code-group
119+
### Generate CA Key and Certificate
113120

114-
```bash [Linux]
115-
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
121+
```bash
122+
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650 -nodes
116123
```
117124

118-
```bash [MacOS]
119-
gsed -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
120-
```
125+
This will create a `key.pem` and `cert.pem` file in the current directory. These files need to be mounted into the cache server container.
121126

122-
```bash [Windows]
123-
[byte[]] -split (((Get-Content -Path ./bin/Runner.Worker.dll -Encoding Byte) | ForEach-Object ToString X2) -join '' -Replace '41004300540049004F004E0053005F0052004500530055004C00540053005F00550052004C00','41004300540049004F004E0053005F0052004500530055004C00540053005F004F0052004C00' -Replace '..', '0x$& ') | Set-Content -Path /path_to_your_runner/bin/Runner.Worker.dll -Encoding Byte
124-
```
127+
### Update the Dockerfile of your runner image
125128

126-
::
129+
```dockerfile [Dockerfile]
130+
# Add the CA certificate to trusted certificates
131+
RUN sudo apt-get install -y ca-certificates
132+
RUN echo "<YOUR GENERATED CERTIFICATE>" | sudo tee /usr/local/share/ca-certificates/cache-server-ca.crt
133+
RUN sudo update-ca-certificates
127134
128-
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.
135+
# Configure NodeJS to use the CA certificate
136+
ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/cache-server-ca.crt
129137
130-
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.
138+
# Configure proxy
139+
ENV http_proxy=http://<your cache server>:<PROXY_PORT>
140+
ENV https_proxy=http://<your cache server>:<PROXY_PORT>
141+
```
131142

132143
## 3. Using the Cache Server
133144

‎docs/content/1.getting-started/4.how-it-works.md

Lines changed: 2 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,6 @@
11
---
22
title: How it works
3-
description: Learn how we built the GitHub Actions Cache Server and how it works without any workflow file changes
3+
description: ''
44
---
55

6-
## 1. Reverse-Engineering the cache server
7-
8-
This is actually a pretty simple process. We just need to look at the requests that the GitHub Actions runner makes to the cache server and then replicate the api routes. We can use the source code of the official `actions/cache` action to see how the requests are made.
9-
10-
GitHub also has very good [documentation](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#matching-a-cache-key) on how the cache keys are matched.
11-
12-
## 2. Getting the actions runner to use our cache server
13-
14-
The whole idea of creating a self-hosted cache server originated from the discovery that the official `actions/cache` action uses an environment variable `ACTIONS_RESULTS_URL` to determine where to send cache requests. This means that we can simply set this environment variable to the base URL of our cache server and the runner will start using it ...right?
15-
16-
Well, not exactly. The `actions/cache` action uses the `ACTIONS_RESULTS_URL` environment variable to determine the base URL of the cache server but we cannot overrid this environment variable in any way.
17-
18-
The default actions runner always overrides the `ACTIONS_RESULTS_URL` environment variable with an internal URL that points to the official GitHub cache server. This is the code that does it:
19-
20-
```c#
21-
var systemConnection = ExecutionContext.Global.Endpoints.Single(x => string.Equals(x.Name, WellKnownServiceEndpointNames.SystemVssConnection, StringComparison.OrdinalIgnoreCase));
22-
Environment["ACTIONS_RUNTIME_URL"] = systemConnection.Url.AbsoluteUri;
23-
Environment["ACTIONS_RUNTIME_TOKEN"] = systemConnection.Authorization.Parameters[EndpointAuthorizationParameters.AccessToken];
24-
if (systemConnection.Data.TryGetValue("CacheServerUrl", out var cacheUrl) && !string.IsNullOrEmpty(cacheUrl))
25-
{
26-
Environment["ACTIONS_CACHE_URL"] = cacheUrl;
27-
}
28-
if (systemConnection.Data.TryGetValue("PipelinesServiceUrl", out var pipelinesServiceUrl) && !string.IsNullOrEmpty(pipelinesServiceUrl))
29-
{
30-
Environment["ACTIONS_RUNTIME_URL"] = pipelinesServiceUrl;
31-
}
32-
if (systemConnection.Data.TryGetValue("GenerateIdTokenUrl", out var generateIdTokenUrl) && !string.IsNullOrEmpty(generateIdTokenUrl))
33-
{
34-
Environment["ACTIONS_ID_TOKEN_REQUEST_URL"] = generateIdTokenUrl;
35-
Environment["ACTIONS_ID_TOKEN_REQUEST_TOKEN"] = systemConnection.Authorization.Parameters[EndpointAuthorizationParameters.AccessToken];
36-
}
37-
if (systemConnection.Data.TryGetValue("ResultsServiceUrl", out var resultsUrl) && !string.IsNullOrEmpty(resultsUrl))
38-
{
39-
Environment["ACTIONS_RESULTS_URL"] = resultsUrl;
40-
}
41-
42-
if (ExecutionContext.Global.Variables.GetBoolean("actions_uses_cache_service_v2") ?? false)
43-
{
44-
Environment["ACTIONS_CACHE_SERVICE_V2"] = bool.TrueString;
45-
}
46-
```
47-
48-
The line `Environment["ACTIONS_RESULTS_URL"] = resultsUrl;` is the one that overrides the `ACTIONS_RESULTS_URL` environment variable with the internal URL.
49-
50-
To allow overriding the `ACTIONS_RESULTS_URL` environment variable, we need to modify the runner binary. This is a bit tricky because the runner is a compiled binary and we cannot simply modify the source code and recompile it. We need to modify the binary itself. So we did just that. We replaced the string `ACTIONS_RESULTS_URL` with `ACTIONS_RESULTS_ORL` (being careful to keep the same length) in the runner binary. This way, the runner will not override the `ACTIONS_RESULTS_URL` environment variable and we can set it to our cache server's base URL.
6+
The cache server acts as a proxy for the actions runner. We forward all cache related requests to our cache server implementation and passthrough any non-cache related requests to the original server.

‎docs/content/index.yml

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ title: GitHub Actions Cache Server
22
description: Easily deploy your own GitHub actions cache without needing to change any workflow files!
33
navigation: false
44
hero:
5-
title: Self-Hosted Cache Server for GitHub Actions
5+
title: Self-Hosted Cache Server<br>for GitHub Actions
66
description: Easily deploy your own GitHub actions cache without needing to change any workflow files!
7-
orientation: horizontal
7+
orientation: vertical
88
links:
99
- label: Get started
1010
icon: i-heroicons-arrow-right-20-solid
@@ -13,20 +13,30 @@ hero:
1313
size: lg
1414
code: |
1515
```yaml [docker-compose.yml]
16-
version: '3.9'
17-
1816
services:
1917
cache-server:
2018
image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
2119
ports:
2220
- '3000:3000'
21+
- '8000:8000'
2322
environment:
2423
API_BASE_URL: http://localhost:3000
24+
CA_KEY_PATH: /run/secrets/ca_key
25+
CA_CERT_PATH: /run/secrets/ca_cert
2526
volumes:
2627
- cache-data:/app/.data
28+
secrets:
29+
- ca_key
30+
- ca_cert
2731
2832
volumes:
2933
cache-data:
34+
35+
secrets:
36+
ca_key:
37+
file: ./key.pem
38+
ca_cert:
39+
file: ./cert.pem
3040
```
3141
features:
3242
items:

0 commit comments

Comments
 (0)