Zoltan Kochan
7fb2bfab4a
Part of https://github.com/pnpm/tasks/issues/191. Wrong claims: - cli: drop the nonexistent `add-user --password` flag and document the terminal/stdin password read; `oci-gc --min-age` and `cache-gc --max-age` are the flags (the `-secs` forms are aliases); `--from` defaults to the `storage` key, not an internal field; `info` and `http` log the same access records; only global and server options have PNPR_* variables. - configuration: `packumentTtl` defaults to 5m; the minimal config now sets `auth.htpasswd.file`, and the auth section says accounts live in memory without it or a backend; grouped hosted registries default their org to `<ecosystem>~<name>`; the handshake is served for any surface; the pipeline surface also satisfies "something must be served"; add `package.update_maintainers` to the audit list. - tls-and-reverse-proxy: remove the invalid `publicUrl:` YAML key and the nonexistent `rate_limiting` setting. - backup-and-restore: `pnpr verify` hashes by default (`--check-hashes` does not exist, `--skip-hashes` skips only the hash comparison); `migrate-storage --verify` compares bytes. - webhooks: audit events do not cover publishes or token creation; the example uses a real action and the `actor` field. - cli: the `RUST_LOG` example keeps `pnpr::audit=info`. - install-acceleration: the `--public-url` host is exempt from the private-address refusal. - shared-side-effects-cache: `pnpm pipeline` publishes workspace-task artifacts. Missing facts: `routes.allowedPrivateNetworks`, the upstream `search` key and canonical `maxAge`, built-in `npm.jsr.io` route, relative path resolution, `log` defaults and `type`, `${VAR:-default}` substitution and the full secret-field list, `oci` defaults, `artifacts.quota` bounds, `migrate-storage` destination rules, `--osv false`, `--packument-ttl` default, S3 `forcePathStyle`/`allowHttp` defaults, grouped org layout, OIDC key table, container image section, `backend:` ignoring the htpasswd and token files. Duplicates and links: health probe bodies, reload procedure, and the resolver allowlist now link to their one home; broken `#secret` anchor fixed; links into the pnpm docs use absolute pnpm.io URLs. Stale history: drop "pnpr v1" and the per-paragraph "Since alpha.N" / "Since pnpm 12.x" prefixes, and the contributor-only extensibility text. Also corrects the `as_filter_directive` doc comment, which claimed `http` quiets the rest of the crate.
3.2 KiB
id, title
| id | title |
|---|---|
| quick-start | Quick start |
Write a config
pnpr routes packages through declared
registries: every origin
(a locally-hosted registry, an upstream like npmjs) is declared explicitly and
claims the package names it serves, and a router resolves each name to exactly
one of them. Save this as pnpr.yaml:
storage: ./storage
auth:
htpasswd:
file: ./htpasswd
# Allow one user to self-register, for the publish step below.
max_users: 1
registries:
# Packages published to this server. The `packages:` map is this
# registry's namespace: only these names can live here.
local:
type: hosted
packages:
'@mycompany/*':
publish: $authenticated
# The public npm registry. No `packages:` map — it serves every name,
# so it must be the last source in the router below.
npmjs:
type: upstream
url: https://registry.npmjs.org/
public: true
# A package resolves to the first source that claims its name:
# your scope goes to the local registry, everything else to npm.
main:
type: router
sources: [local, npmjs]
# The bare server URL serves the router.
defaultRegistry: main
Replace @mycompany with your own scope. There is no fall-through between
registries: a @mycompany/* package that isn't published locally is a
definitive 404, never a request to npmjs. This is what closes
dependency confusion.
Start the server
pnpr -c ./pnpr.yaml
It listens on 127.0.0.1:7677. Running plain pnpr with no config works
too. The bundled config proxies npmjs and provides a local hosted registry at
/npm/~local/, whose packages need a login. It allows no self-registration,
so create accounts with pnpr add-user.
Point a client at it
Configure pnpm (or npm/yarn) to use the local server as its registry:
pnpm config set registry http://127.0.0.1:7677/npm/
Now pnpm install fetches packages through pnpr. Packages proxied from the
upstream are cached, so subsequent installs are served locally.
Each registry is also directly addressable at
http://127.0.0.1:7677/npm/~<name>/. For example, you can point only your scope
at the hosted registry instead of using the router.
Publish a package
Create a user and publish:
pnpm login --registry http://127.0.0.1:7677/npm/
pnpm publish --registry http://127.0.0.1:7677/npm/
The publish routes through the router to the local hosted registry.
Publishing a package that resolves to an upstream, or whose name no registry
claims, is rejected.
Where to go next
- CLI reference: every flag
pnpraccepts. - Configuration: write your own config, including registries, access rules, and auth.
- Reverse proxy and TLS: set up Nginx, Caddy, Traefik, or a cloud load balancer for production.
- Webhooks and event notifications: stream audit events and storage notifications to external webhooks.
- Backup and restore: snapshot and restore package storage and user records.
- Install acceleration: let pnpr resolve your dependency graph to speed up installs.