Skip to content

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.

Terminal window
E=https://entrepot.example.com
api() { curl -fsS -H "Authorization: Bearer $ADMIN" -H 'Content-Type: application/json' "$@"; }
  1. 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 default file store is created automatically when none is declared. The examples use default; a large Docker registry is often better on S3.

  2. 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"}
    }'

    Useful proxy settings: metadataTtlSeconds (indexes, packuments and tags, default 3600), contentTtlSeconds (artifacts, default 0 = immutable), negativeCacheTtlSeconds (upstream 404s, default 300) and routingRule.

  3. 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.allowRedeploy is true. Docker hosted repositories allow moving tags by default; set "hosted": {"allowRedeploy": false} for immutable tags.

  4. 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.

  5. Grant access

    New repositories are visible only to administrators (and to everyone if anonymousRead is true). Bind roles to OIDC groups:

    Terminal window
    # everyone who is logged in can read every repository
    api -X POST $E/api/v1/role-bindings -d '{"role":"viewer","subjectType":"authenticated","repositoryPattern":"*"}'
    # the developers group can publish to the hosted repositories
    api -X POST $E/api/v1/role-bindings -d '{"role":"developer","subjectType":"group","subject":"developers","repositoryPattern":"*-internal"}'

    See Authorization for roles, subjects and patterns.

  6. 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.