Getting Started

Running with Docker Compose

docker compose up -d

This starts:

MinIO on port 9000 (console on 9001)
Package Registry on port 8080

Configuration

All configuration is via environment variables:

Variable	Default	Description
`LISTEN_ADDR`	`:8080`	HTTP listen address
`MINIO_ENDPOINT`	`localhost:9000`	MinIO server address
`MINIO_ACCESS_KEY`	(required)	MinIO access key
`MINIO_SECRET_KEY`	(required)	MinIO secret key
`MINIO_BUCKET`	`packages`	Bucket name
`MINIO_PREFIX`	(none)	Object key prefix for all cached packages
`MINIO_USE_SSL`	`false`	Use TLS for MinIO
`UPSTREAM_URL`	`https://pypi.org`	PyPI upstream URL
`NPM_UPSTREAM_URL`	`https://registry.npmjs.org`	npm upstream URL
`NEXT_HOP_URL`	(none)	PyPI next-hop proxy
`NPM_NEXT_HOP_URL`	(none)	npm next-hop proxy
`CACHE_TTL`	`5m`	Metadata cache TTL
`KAFKA_BROKERS`	(none)	Kafka brokers for audit logging
`KAFKA_AUDIT_TOPIC`	`audit-events`	Kafka topic for audit events

Storage Layout

All cached packages are stored in a single MinIO bucket. PyPI packages are stored at the bucket root, npm packages under an npm/ prefix:

<bucket>/
  six/six-1.17.0-py2.py3-none-any.whl
  requests/requests-2.31.0-py3-none-any.whl
  npm/is-odd/is-odd-3.0.1.tgz
  npm/@sindresorhus/is/is-6.0.0.tgz

Using a prefix

Set MINIO_PREFIX to store all cached packages under a common prefix. This is useful when sharing a bucket with other applications or organizing data by environment:

export MINIO_PREFIX="cache/packages"

With this prefix, objects are stored as:

<bucket>/
  cache/packages/six/six-1.17.0-py2.py3-none-any.whl
  cache/packages/npm/is-odd/is-odd-3.0.1.tgz

The prefix is transparent to the rest of the system — it is automatically prepended on writes and stripped on reads. All API responses, package listings, and management endpoints work identically regardless of whether a prefix is configured.

Client Configuration

See the Client Configuration guide for detailed setup instructions for pip, uv, npm, yarn, and pnpm.

Quick start:

# PyPI
pip install --index-url http://localhost:8080/simple/ requests

# npm
npm install --registry http://localhost:8080 lodash