🚀 Nx Caching Server

Overview

Nx Caching Server is a custom remote caching server for Nx, written in Go. This implementation follows the Nx OpenAPI specification (v20.8+) and provides a lightweight, self-hosted remote cache solution.

Since Nx 20.8, you can use your own caching server by implementing their OpenAPI spec. This server handles storage, retrieval, and optional bearer-token authentication.

Configuration

Configure the server using environment variables. All configuration options are optional and have sensible defaults.

Getting Started

Build from Source

Build and run the server from source code:

1. Clone the repository

git clone https://github.com/enxtur/nx-caching-server.git
cd nx-caching-server

2. Build the binary

go build -o nx-caching-server ./main.go

3. Run it

./nx-caching-server

4. With custom settings

STORAGE_DIR=./cache-data \
PORT=8090 \
AUTH_TOKEN=super-secret-123 \
CLEANUP_THRESHOLD=24h \
./nx-caching-server

Configuring Nx Workspace

Point your Nx workspace to the caching server by setting these environment variables (or add them to .env / CI config):

Without Authentication

export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=http://localhost:8090

With Authentication

export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=http://localhost:8090
export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=your-secure-token-here

Then run your tasks as usual:

npx nx run-many --target=build --all

Nx will automatically read from / write to your self-hosted cache, significantly speeding up your build times across different machines and CI/CD pipelines.

API Reference

The server implements the Nx OpenAPI specification (v20.8+). All endpoints support optional bearer token authentication when AUTH_TOKEN is configured.

Health Check

Cache Operations

All cache operations use the same endpoint with different HTTP methods:

Authentication

When AUTH_TOKEN is set, all requests must include a Bearer token in the Authorization header:

Authorization: Bearer your-secure-token-here

Requests without a valid token will receive 401 Unauthorized.

Docker Deployment

Using Pre-built Image

Pull the pre-built image from Docker Hub:

docker pull enxtur/nx-caching-server

Run with Docker

Example with persistent storage and authentication:

docker run -d \
  --name nx-cache \
  -p 8090:8090 \
  -v $(pwd)/nx-cache-data:/data \
  -e STORAGE_DIR=/data \
  -e AUTH_TOKEN=your-secure-token-here \
  -e CLEANUP_THRESHOLD=48h \
  enxtur/nx-caching-server

Build from Source

Or build your own image from source:

docker build -t nx-caching-server .

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  nx-cache:
    image: enxtur/nx-caching-server:latest
    container_name: nx-caching-server
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ./nx-cache-data:/data
    environment:
      - STORAGE_DIR=/data
      - PORT=8090
      - AUTH_TOKEN=your-secure-token-here          # remove this line if you want no authentication
      - CLEANUP_THRESHOLD=24h

Start it:

docker compose up -d

License