@renatorodrigues/cacheiro-runner

Reference runner for @renatorodrigues/cacheiro. Loads config via the config npm package, validates it with AJV, instantiates a store, then starts a Cacheiro server. Ships with FileSystemStore by default — swap in any other store package to change the backend.

This is a runnable application, not a library. It is not published to npm (private: true). Use it as-is, fork it, or write your own runner on top of cacheiro's exported API.

Looking for a ready-to-run Docker image? Prebuilt images for the filesystem, S3, GCS and Azure stores are published to GHCR as Cacheiro Instants.

Requirements

• Node.js 22+

Getting started

cp config/local.jsonc.example config/local.jsonc
# edit config/local.jsonc — set auth.token and adjust storeOptions
npm run dev

Configuration

Two layers: JSON config files + environment variables. Environment variables always win.

Config files

Resolved in order — later entries override earlier ones:

File	Purpose
config/default.json	Base defaults (port 3000, filesystem store, 100 MB body limit)
config/production.json	Production overrides — applied when NODE_ENV=production
config/local.jsonc	Local overrides — highest file priority, gitignored, create from local.jsonc.example
config/custom-environment-variables.json	Maps env vars to config keys — overrides all files when the env var is set

Config values

See Config values reference below.

Environment variables

See Environment variables reference below.

Deployment

Dev (hot reload)

npm run dev

Node (built)

npm run build
node dist/index.js

PM2

npm start
# uses ecosystem.config.cjs — runs node dist/index.js under pm2-runtime

Docker

Build from the repo root (the Dockerfile needs access to the full monorepo):

docker build -f packages/cacheiro-runner/Dockerfile -t cacheiro-runner .

Run:

docker run -p 3000:3000 \
  -e CACHEIRO_AUTH_TOKEN=my-secret-token \
  -e NODE_ENV=production \
  -v $(pwd)/cache:/cache \
  cacheiro-runner

With TLS:

docker run -p 3000:3000 \
  -e CACHEIRO_AUTH_TOKEN=my-secret-token \
  -e CACHEIRO_TLS_CERT_FILE=/certs/cert.pem \
  -e CACHEIRO_TLS_KEY_FILE=/certs/key.pem \
  -e NODE_ENV=production \
  -v $(pwd)/cache:/cache \
  -v $(pwd)/certs:/certs:ro \
  cacheiro-runner

To use a cloud store (S3, GCS, Azure), use this runner as a starting point: update src/index.ts to import and instantiate the appropriate store package, and update the config files to match. See each store package's README for config fields and conventional env var names. config/local.jsonc.example includes working storeOptions examples for all supported stores.

Note: The Dockerfile is wired for FileSystemStore only. If you swap the store, update the Dockerfile accordingly — add the store package's package.json copy, build step, and dist copy to both stages.

Development

npm run dev            # watch + watch:others (full hot reload — server and dep packages)
npm run watch          # tsx watch src/index.ts — server only
npm run watch:others   # rebuilds dep packages on change (silent unless error)
npm run build          # compile TypeScript
npm test               # vitest run
npm run test:watch     # watch mode
npm run lint           # oxlint
npm run lint:fix       # oxlint --fix
npm run fmt            # oxfmt
npm run fmt:check      # oxfmt --check

Config values reference

Key	Default	Description
server.port	3000	Port to listen on
server.host	127.0.0.1	Host to bind to. Use 0.0.0.0 to expose on all interfaces.
server.bodyLimitMb	100	Max request body size in MB
server.banner	true	Show ASCII art startup banner. When false, prints a compact single-line header instead.
server.infobox	true	Show the info box with version, URL, and store details. When false, the version is shown inline instead.
server.logFormat	unset	pretty or json. Unset means pretty outside NODE_ENV=production and json in production.
server.tls.certFile	—	Path to PEM certificate file. When set (with keyFile), enables HTTPS.
server.tls.keyFile	—	Path to PEM private key file.
server.tls.caFile	—	Path to CA certificate file (optional).
auth.token	"change-me"	Bearer token required on all requests. Omit auth (or token) entirely to disable auth — passing "" still works but is deprecated and will be rejected in the next major version.
auth.readOnlyToken	—	Optional bearer token granting read-only access (GET only, no PUT). Requires auth.token to be set. Must differ from auth.token.
storeOptions.cacheDirectory	"./cache"	Directory where artifacts are stored.
storeOptions.ttlDays	7	Artifact TTL in days. 0 disables expiration.
storeOptions.sweepIntervalHours	24	How often to sweep for expired artifacts (hours). 0 disables the sweep.

Environment variables reference

Variable	Config key	Default
CACHEIRO_AUTH_TOKEN	auth.token	"change-me"
CACHEIRO_AUTH_READ_ONLY_TOKEN	auth.readOnlyToken	—
CACHEIRO_PORT	server.port	3000
CACHEIRO_HOST	server.host	127.0.0.1
CACHEIRO_BODY_LIMIT_MB	server.bodyLimitMb	100
CACHEIRO_BANNER	server.banner	true
CACHEIRO_INFOBOX	server.infobox	true
CACHEIRO_LOG_FORMAT	server.logFormat	—
CACHEIRO_TLS_CERT_FILE	server.tls.certFile	—
CACHEIRO_TLS_KEY_FILE	server.tls.keyFile	—
CACHEIRO_TLS_CA_FILE	server.tls.caFile	—
CACHEIRO_CACHE_DIRECTORY	storeOptions.cacheDirectory	./cache
CACHEIRO_CACHE_TTL_DAYS	storeOptions.ttlDays	7
CACHEIRO_CACHE_SWEEP_INTERVAL_HOURS	storeOptions.sweepIntervalHours	24