pkg-proxy/docs/configuration.md

Configuration

The proxy can be configured via command line flags, environment variables, or a configuration file. Command line flags take precedence over environment variables, which take precedence over the configuration file.

Configuration File

Create a YAML or JSON file and pass it with -config:

proxy serve -config config.yaml

See config.example.yaml in the repository root for a complete example.

Server Settings

Config	Environment	Flag	Default	Description
listen	PROXY_LISTEN	-listen	:8080	Address to listen on
base_url	PROXY_BASE_URL	-base-url	http://localhost:8080	Public URL for the proxy

Storage

The proxy stores cached artifacts using gocloud.dev/blob, supporting local filesystem and S3-compatible storage.

Local Filesystem

storage:
  url: "file:///var/cache/proxy"

Or using the legacy path option:

storage:
  path: "./cache/artifacts"

Config	Environment	Flag	Description
storage.url	PROXY_STORAGE_URL	-storage-url	Storage URL (file:// or s3://)
storage.path	PROXY_STORAGE_PATH	-storage-path	Local path (deprecated, use url)
storage.max_size	PROXY_STORAGE_MAX_SIZE	-	Max cache size (e.g., "10GB")

Amazon S3

storage:
  url: "s3://my-bucket"

Configure credentials via environment variables:

export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_REGION=us-east-1

S3-Compatible (MinIO, etc.)

storage:
  url: "s3://my-bucket?endpoint=http://localhost:9000&disableSSL=true&s3ForcePathStyle=true"

Database

The proxy supports SQLite (default) and PostgreSQL for storing package metadata.

SQLite

database:
  driver: "sqlite"
  path: "./cache/proxy.db"

Config	Environment	Flag	Description
database.driver	PROXY_DATABASE_DRIVER	-database-driver	sqlite or postgres
database.path	PROXY_DATABASE_PATH	-database-path	SQLite file path

PostgreSQL

database:
  driver: "postgres"
  url: "postgres://user:password@localhost:5432/proxy?sslmode=disable"

Config	Environment	Flag	Description
database.url	PROXY_DATABASE_URL	-database-url	PostgreSQL connection URL

Logging

log:
  level: "info"
  format: "text"

Config	Environment	Flag	Values
log.level	PROXY_LOG_LEVEL	-log-level	debug, info, warn, error
log.format	PROXY_LOG_FORMAT	-log-format	text, json

Upstream Registries

Override default upstream registry URLs:

upstream:
  npm: "https://registry.npmjs.org"
  cargo: "https://index.crates.io"
  cargo_download: "https://static.crates.io/crates"

Authentication

Configure authentication for private upstream registries. Auth is matched by URL prefix, and credentials can reference environment variables using ${VAR_NAME} syntax.

Bearer Token

Used by npm, GitHub Package Registry, and many other registries:

upstream:
  auth:
    "https://registry.npmjs.org":
      type: bearer
      token: "${NPM_TOKEN}"
    "https://npm.pkg.github.com":
      type: bearer
      token: "${GITHUB_TOKEN}"

Basic Authentication

Used by PyPI, Artifactory, and others:

upstream:
  auth:
    "https://pypi.org":
      type: basic
      username: "__token__"
      password: "${PYPI_TOKEN}"
    "https://artifactory.mycompany.com":
      type: basic
      username: "deploy"
      password: "${ARTIFACTORY_PASSWORD}"

Custom Header

For registries that use non-standard authentication headers:

upstream:
  auth:
    "https://maven.mycompany.com":
      type: header
      header_name: "X-Auth-Token"
      header_value: "${MAVEN_TOKEN}"

URL Matching

Auth configs are matched by URL prefix. The longest matching prefix wins, so you can configure different credentials for different paths:

upstream:
  auth:
    # All requests to this registry
    "https://registry.mycompany.com":
      type: bearer
      token: "${REGISTRY_TOKEN}"
    # Override for a specific scope
    "https://registry.mycompany.com/@private":
      type: bearer
      token: "${PRIVATE_TOKEN}"

Cooldown

The cooldown feature hides package versions published too recently, giving the community time to spot malicious releases before they reach your projects. When a version is within its cooldown period, it's stripped from metadata responses so package managers won't install it.

cooldown:
  default: "3d"
  ecosystems:
    npm: "7d"
    cargo: "0"
  packages:
    "pkg:npm/lodash": "0"
    "pkg:npm/@babel/core": "14d"

Config	Environment	Description
cooldown.default	PROXY_COOLDOWN_DEFAULT	Global default cooldown
cooldown.ecosystems	-	Per-ecosystem overrides
cooldown.packages	-	Per-package overrides (keyed by PURL)

Durations support days (7d), hours (48h), and minutes (30m). Set to 0 to disable.

Resolution order: package override, then ecosystem override, then global default. This lets you set a conservative default while exempting trusted packages.

Currently supported for npm, PyPI, pub.dev, Composer, Cargo, NuGet, Conda, RubyGems, and Hex. These ecosystems include publish timestamps in their metadata.

Note: Hex cooldown requires disabling registry signature verification since the proxy re-encodes the protobuf payload without the original signature. Set HEX_NO_VERIFY_REPO_ORIGIN=1 or configure your repo with no_verify: true.

Docker

SQLite with Local Storage

docker compose up

PostgreSQL with Local Storage

docker compose --profile postgres up

PostgreSQL with S3 (MinIO)

docker compose --profile s3 up

Example Configurations

Minimal (defaults)

listen: ":8080"

Production with PostgreSQL and S3

listen: ":8080"
base_url: "https://proxy.example.com"

storage:
  url: "s3://my-cache-bucket"
  max_size: "100GB"

database:
  driver: "postgres"
  url: "postgres://proxy:secret@db.example.com:5432/proxy?sslmode=require"

log:
  level: "info"
  format: "json"

Private npm Registry

listen: ":8080"
base_url: "http://localhost:8080"

upstream:
  npm: "https://npm.pkg.github.com"
  auth:
    npm:
      type: bearer
      token: "${GITHUB_TOKEN}"