build(docker): add caged image variant

Author: LouisHaftmann

.dockerignore

@@ -1,10 +1,19 @@
 node_modules/
+.git/
 .github/
 .nitro/
 .output/
 .vscode/
 data/
 .env*
 .eslintcache
-test/
-certs/
+tests/
+certs/
+install/
+benchmark.ts
+docker-compose.yml
+vitest.config.ts
+prettier.config.js
+eslint.config.js
+README.md
+LICENSE

.github/workflows/ci-cd.yml

@@ -104,3 +104,23 @@ jobs:
           labels: ${{ steps.meta.outputs.labels }}
           build-args: |
             BUILD_HASH=${{ steps.build_hash.outputs.COMMIT_SHA }}
+
+      - name: Extract metadata (tags, labels) for Docker (caged)
+        id: meta-caged
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            dev-caged
+
+      - name: Build and push (caged)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta-caged.outputs.tags }}
+          labels: ${{ steps.meta-caged.outputs.labels }}
+          build-args: |
+            BUILD_HASH=${{ steps.build_hash.outputs.COMMIT_SHA }}
+            BASE_IMAGE=platformatic/node-caged:25-alpine

.github/workflows/release.yml

@@ -137,6 +137,29 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
 
+      - name: Extract metadata (tags, labels) for Docker (caged)
+        id: meta-caged
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}-caged,value=${{ needs.release.outputs.RELEASE_TAG }}
+            type=semver,pattern={{major}}.{{minor}}-caged,value=${{ needs.release.outputs.RELEASE_TAG }}
+            type=semver,pattern={{major}}-caged,value=${{ needs.release.outputs.RELEASE_TAG }}
+            latest-caged
+            dev-caged
+
+      - name: Build and push (caged)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta-caged.outputs.tags }}
+          labels: ${{ steps.meta-caged.outputs.labels }}
+          build-args: |
+            BASE_IMAGE=platformatic/node-caged:25-alpine
+
   deploy-chart:
     name: 🚀 Build and push Helm chart
     permissions:

Dockerfile

@@ -1,22 +1,25 @@
-FROM node:24-alpine AS builder
+ARG BASE_IMAGE=node:25-alpine
+
+FROM ${BASE_IMAGE} AS builder
 
 WORKDIR /app
 
-RUN npm install -g pnpm@latest-10
+RUN --mount=type=cache,target=/root/.npm npm install -g pnpm@latest-10
 
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+
 RUN --mount=type=cache,target=/root/.local/share/pnpm/store pnpm fetch --prod
+RUN --mount=type=cache,target=/root/.local/share/pnpm/store pnpm install --frozen-lockfile --prod --offline
 
 COPY . .
-RUN --mount=type=cache,target=/root/.local/share/pnpm/store pnpm install --frozen-lockfile --prod --offline
 
 ARG BUILD_HASH
 ENV BUILD_HASH=${BUILD_HASH}
 RUN pnpm run build
 
 # --------------------------------------------
 
-FROM node:24-alpine AS runner
+FROM ${BASE_IMAGE} AS runner
 
 ENV NITRO_CLUSTER_WORKERS=1
 

install/kubernetes/github-actions-cache-server/templates/NOTES.txt

@@ -9,4 +9,12 @@ GitHub Actions Cache Server has been deployed!
   API URL:   {{ .Values.config.apiBaseUrl }}
 {{- end }}
 
+{{- if eq (.Values.image.variant | default "") "caged" }}
+
+⚠️  EXPERIMENTAL: You are using the "caged" image variant (V8 pointer compression).
+   Each V8 isolate is limited to a 4 GB heap.
+   Test in staging first and monitor memory/latency.
+   More info: https://blog.platformatic.dev/we-cut-nodejs-memory-in-half
+{{- end }}
+
 Docs: https://gha-cache-server.falcondev.io/getting-started

install/kubernetes/github-actions-cache-server/templates/deployment.yaml

@@ -41,7 +41,7 @@ spec:
         - name: {{ .Chart.Name }}
           securityContext:
             {{- toYaml .Values.securityContext | nindent 12 }}
-          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}{{ if .Values.image.variant }}-{{ .Values.image.variant }}{{ end }}"
           imagePullPolicy: {{ .Values.image.pullPolicy }}
           ports:
             - name: cache

install/kubernetes/github-actions-cache-server/values.yaml

@@ -9,6 +9,17 @@ image:
   pullPolicy: IfNotPresent
   # Overrides the image tag whose default is the chart appVersion.
   tag: ''
+  # -- (experimental) Image variant to use. Set to "caged" to use the platformatic/node-caged
+  # based image, which enables V8 pointer compression for ~50% lower memory usage.
+  # See: https://blog.platformatic.dev/we-cut-nodejs-memory-in-half
+  #
+  # Caveats:
+  # - Each V8 isolate is limited to a 4 GB heap. Not suitable for workloads that
+  #   require more than 4 GB per isolate.
+  # - Expect ~2-4% higher average latency, though p99/max latency may improve due
+  #   to reduced GC pressure.
+  # When set, "-caged" is appended to the resolved image tag.
+  variant: ''
 
 imagePullSecrets: []
 nameOverride: ''

package.json

@@ -4,7 +4,7 @@
   "version": "9.2.0",
   "private": true,
   "engines": {
-    "node": "24",
+    "node": "25",
     "pnpm": "10"
   },
   "scripts": {