First repositories
A typical setup per ecosystem is three repositories:
npm-group (group: one URL for clients) ┌────┴─────┐ npm-internal npm-proxy ──► https://registry.npmjs.org (hosted) (proxy)Clients read from the group; CI publishes to the hosted repository; the proxy caches the public registry. Because groups prefer hosted packages, a public package can never shadow one of your internal names.
The examples use an administrator token in $ADMIN (a token of a member of
auth.adminGroups, or the bootstrap token while you set up) and
E=https://entrepot.example.com. Every request below is also possible in the
UI (Repositories → Create repository) and with
Terraform.
E=https://entrepot.example.comapi() { curl -fsS -H "Authorization: Bearer $ADMIN" -H 'Content-Type: application/json' "$@"; }-
Pick a blob store
Every repository stores its content in one blob store, chosen at creation and immutable afterwards. List the stores you have:
Terminal window api $E/api/v1/blob-stores | jq '.[] | {name, type}'A
defaultfile store is created automatically when none is declared. The examples usedefault; a large Docker registry is often better on S3. -
Create the proxies
Terminal window api -X POST $E/api/v1/repositories -d '{"name": "npm-proxy", "format": "npm", "kind": "proxy", "blobStore": "default","proxy": {"remoteUrl": "https://registry.npmjs.org"}}'Terminal window api -X POST $E/api/v1/repositories -d '{"name": "pypi-proxy", "format": "pypi", "kind": "proxy", "blobStore": "default","proxy": {"remoteUrl": "https://pypi.org"}}'Terminal window api -X POST $E/api/v1/repositories -d '{"name": "docker-hub", "format": "docker", "kind": "proxy", "blobStore": "default","proxy": {"remoteUrl": "https://registry-1.docker.io","username": "my-hub-user", "password": "dckr_pat_…"}}'Upstream credentials are optional; they give the proxy your account’s Docker Hub pull quota and are sent only to the upstream host. The password is encrypted at rest and never returned.
Useful proxy settings:
metadataTtlSeconds(indexes, packuments and tags, default 3600),contentTtlSeconds(artifacts, default 0 = immutable),negativeCacheTtlSeconds(upstream 404s, default 300) androutingRule. -
Create the hosted repositories
Terminal window api -X POST $E/api/v1/repositories -d '{"name":"npm-internal","format":"npm","kind":"hosted","blobStore":"default"}'api -X POST $E/api/v1/repositories -d '{"name":"pypi-internal","format":"pypi","kind":"hosted","blobStore":"default"}'api -X POST $E/api/v1/repositories -d '{"name":"docker-internal","format":"docker","kind":"hosted","blobStore":"default"}'Hosted npm and PyPI repositories reject re-publishing an existing version unless
hosted.allowRedeployistrue. Docker hosted repositories allow moving tags by default; set"hosted": {"allowRedeploy": false}for immutable tags. -
Put them behind groups
Members are searched in order. Put hosted repositories first.
Terminal window api -X POST $E/api/v1/repositories -d '{"name": "npm-group", "format": "npm", "kind": "group", "blobStore": "default","group": {"members": ["npm-internal", "npm-proxy"]}}'api -X POST $E/api/v1/repositories -d '{"name": "pypi-group", "format": "pypi", "kind": "group", "blobStore": "default","group": {"members": ["pypi-internal", "pypi-proxy"]}}'Docker groups work the same way. Apt and Yum don’t support groups yet.
-
Grant access
New repositories are visible only to administrators (and to everyone if
anonymousReadistrue). Bind roles to OIDC groups:Terminal window # everyone who is logged in can read every repositoryapi -X POST $E/api/v1/role-bindings -d '{"role":"viewer","subjectType":"authenticated","repositoryPattern":"*"}'# the developers group can publish to the hosted repositoriesapi -X POST $E/api/v1/role-bindings -d '{"role":"developer","subjectType":"group","subject":"developers","repositoryPattern":"*-internal"}'See Authorization for roles, subjects and patterns.
-
Point clients at the groups
Terminal window npm config set registry https://entrepot.example.com/repository/npm-group/pip config set global.index-url https://entrepot.example.com/repository/pypi-group/simple/The UI’s Set up client panel on each repository shows these snippets pre-filled, both for a workstation and for GitLab CI.