Skip to content

Docker Repositories

This page covers using the Docker CLI with CloudRepo private Docker repositories.

Push, pull and build with Docker against a CloudRepo Docker repository. CloudRepo speaks the Docker Registry HTTP API V2, so the Docker CLI needs nothing beyond docker login.

  • A Docker repository. If you have none, see Creating a Repository.
  • A repository token that reaches it, with Download and publish packages if you will push. See Repository Tokens: Create One and Authenticate. It starts with crp_v1_, or crk_v1_ for an organization token. An npm-format token (crn_v1_) does not authenticate here. The password is the token, and the username is not checked: use your email address, as every other client does, or the word token for an organization token.
  • The Connection Settings of the repository show its image reference and ready-made CI snippets with your names filled in.

Used on this page only, never saved. Never enter a token or password here.

1. Log in to the host. Pipe the token to docker login on standard input:

Terminal
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \
--username you@example.com \
--password-stdin

Expected: Login Succeeded. To be prompted instead, run docker login your-org.mycloudrepo.io and enter your email address and the token.

2. Build and push. The image reference carries the repository: the host, the literal repositories/ segment, your repository, then the image and tag.

Terminal
docker build -t your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0 .
docker push your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0

To push an image you already have, tag it with that reference first:

Terminal
docker tag my-app:1.0.0 your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0

3. Pull. The login you made applies. You logged in to the bare host, but you pull the /repositories/ path:

Terminal
docker pull your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0

For GitHub Actions, GitLab CI, CircleCI, Jenkins, Buildkite and the like, keep the token in the platform’s secret store, expose it as the environment variable CLOUDREPO_TOKEN, and use the same login as above:

Terminal
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \
--username you@example.com \
--password-stdin

--password-stdin is the Docker CLI’s option for reading the password from standard input instead of the command line. Never commit the token to a repository. The variable name is yours to choose: the admin portal’s ready-made GitHub Actions and GitLab CI snippets call it CLOUDREPO_PASSWORD, and the value is the same repository token either way.

Install packages from CloudRepo in a Docker build

Section titled “Install packages from CloudRepo in a Docker build”

When a docker build installs your private Maven, Python or npm packages from CloudRepo, the step that downloads them needs your repository token. Give it to that step as a build secret, never as a build argument: Docker records build arguments in the image’s history, so the token would travel with the image. Docker’s documentation advises against build arguments for credentials. See Build secrets.

Pass the username the same way. It is the email address of the account that created the token. Both values come from environment variables, so neither appears in the command:

Terminal
docker build \
--secret id=cloudrepo_user,env=CLOUDREPO_USERNAME \
--secret id=cloudrepo,env=CLOUDREPO_TOKEN \
-t my-app .

In the Dockerfile, mount the secrets on the RUN step that downloads packages. env=CLOUDREPO_TOKEN sets that variable for that one step, and the client reads it from there. Keep the first line, # syntax=docker/dockerfile:1: mounting a secret as a variable needs Dockerfile syntax 1.10 or later, and that line fetches it for any Docker with BuildKit (the default builder since Docker Engine 23).

Do not write the token into a file in that step: a file a RUN step leaves behind is part of the image. The examples below keep the token in the variable and write only the variable’s name to disk.

If the variable is not set when you run docker build, Docker passes an empty secret rather than failing, and the download step is refused as if the token were wrong.

Maven. A multi-stage build is the norm: the build stage has Maven and the JDK, and the runtime stage gets only the jar. settings.xml names the variables, never their values, and Maven reads ${env.NAME} when it runs. The <id> must match the repository <id> in your pom.xml (Repository Tokens: Create One and Authenticate shows both files).

settings.xml (next to the Dockerfile)
<settings>
<servers>
<server>
<id>cloudrepo</id>
<username>${env.CLOUDREPO_USERNAME}</username>
<password>${env.CLOUDREPO_TOKEN}</password>
</server>
</servers>
</settings>
Dockerfile - Maven
# syntax=docker/dockerfile:1
FROM maven:3.9-eclipse-temurin-17 AS build
WORKDIR /app
COPY settings.xml /root/.m2/settings.xml
COPY pom.xml .
COPY src ./src
RUN --mount=type=secret,id=cloudrepo_user,env=CLOUDREPO_USERNAME \
--mount=type=secret,id=cloudrepo,env=CLOUDREPO_TOKEN \
mvn -B package -DskipTests
FROM eclipse-temurin:17-jre
COPY --from=build /app/target/*.jar /app/app.jar
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

pip. pip finds the credential for the index’s host in ~/.netrc, so the index URL carries none. Mount a netrc file that holds only the CloudRepo entry as a build secret, on the RUN step that installs. Keep the file outside the build context and readable by you alone (chmod 600). The login is the plain email address of the account that created the token:

~/cloudrepo.netrc
machine your-org.mycloudrepo.io
login you@example.com
password YOUR_REPOSITORY_TOKEN
Terminal
docker build --secret id=netrc,src=$HOME/cloudrepo.netrc -t my-app .
Dockerfile - pip
# syntax=docker/dockerfile:1
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=secret,id=netrc,target=/root/.netrc \
pip install --no-cache-dir \
--index-url https://your-org.mycloudrepo.io/repositories/your-repo/simple/ \
-r requirements.txt
COPY . .
CMD ["python", "app.py"]

This image runs as root, so the file mounts at /root/.netrc. For another user, mount it in that user’s home directory.

npm. npm sends the token on its own, so it needs only the cloudrepo secret. The project’s .npmrc names the variable, and npm reads it when it runs:

.npmrc
@yourscope:registry=https://your-org.mycloudrepo.io/repositories/your-repo/
//your-org.mycloudrepo.io/repositories/your-repo/:_authToken=${NPM_TOKEN}

Send your scope’s packages to this repository; every other package still comes from the public npm registry. Replace @yourscope with your scope.

Dockerfile - npm
# syntax=docker/dockerfile:1
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json .npmrc ./
RUN --mount=type=secret,id=cloudrepo,env=NPM_TOKEN \
npm ci
COPY . .
CMD ["node", "index.js"]

A hosted repository holds only what was published to it. To install public packages through CloudRepo as well, create an npm proxy repository and use that as the registry.

/v2/_catalog is not implemented and answers 405 UNSUPPORTED. Use the admin portal to see what a repository holds.

docker login returns 401 Unauthorized

  • Use the repository token as the password, not your admin-portal password.
  • Check on the Repository Tokens page that the token has not been revoked or expired.

docker push returns 403 Forbidden after a successful login

  • The token cannot write to the repository. Pushing needs a Download and publish packages token, and the user who created the token needs read and write access, not read only. Check the token’s access on the Repository Tokens page.

docker push or docker pull cannot find the repository

  • Check the reference carries the literal repositories/ segment: your-org.mycloudrepo.io/repositories/your-repo/<image>:<tag>. Omitting it is the most common mistake, because docker login does not use it, so a successful login cannot warn you that the reference is malformed.

A Docker proxy repository fetches an image from another registry when you pull it, and CloudRepo stores a copy of what it fetched in your repository. This section points one at Docker Hub, logs in to it and pulls an official image through it.

1. Create the proxy repository. In the admin portal, open Create repository and choose:

  • Format: Docker.
  • Kind: Proxy.
  • Upstream: Docker Hub, chosen for you.
  • Name: a name for the proxy, such as docker-hub. It appears in every image reference you pull through it, and the form shows that reference as you type.

Then select Create repository.

A new proxy pulls from Docker Hub anonymously. To make it pull as your Docker Hub account instead, including images that are private to that account, give the repository an upstream credential. See Upstream Credentials.

2. Log in to the host. Use a repository token that reaches the proxy, as in Before you start, and log in to the host alone, the same login as in Connect Docker:

Terminal
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \
--username you@example.com \
--password-stdin

3. Pull an image. The reference is the host, the literal repositories/ segment, your proxy’s ID, then the image and tag:

Terminal
docker pull your-org.mycloudrepo.io/repositories/docker-hub/alpine:latest

The proxy’s Connection Settings show the login and pull commands with your names filled in.

An official image on Docker Hub, such as Alpine, is pulled by its short name. On a Docker Hub proxy, an image name with no slash in it is fetched from Docker Hub as library/ plus that name, so the pull above asks Docker Hub for library/alpine. A name with a slash is fetched as written: myuser/myimage asks for myuser/myimage. Writing library/alpine yourself, as in your-org.mycloudrepo.io/repositories/docker-hub/library/alpine:latest, asks for the same library/alpine.

The short-name rule belongs to a Docker Hub proxy. A proxy of another Docker upstream, such as GitHub Container Registry, fetches the name as written.

CloudRepo refuses a docker push to a proxy repository. Push your own images to a hosted Docker repository, as in Connect Docker, and use the proxy for pulling.

A group repository is a single address that resolves against several member repositories in a priority order you set. It gives a team one registry URL that serves images kept in more than one repository.

Create it in the admin portal with Docker as the format and Group as the kind, then add member repositories and order them. A Docker group asks its Hosted members first, in the priority you set. When a Hosted member holds any tag of an image name, the group answers every tag of that name from its Hosted members only. Its Proxy members aren’t asked for any tag of that name. If you delete every tag of that name, the group answers not found for it until you push the name again. It doesn’t fetch it from Docker Hub. A pull by digest follows this rule too: a manifest of that name is served from the Hosted members only. Layers are still fetched by the digest the manifest names. For this rule, alpine and library/alpine count as one name. A tag is still pulled under the name it was pushed with: a hosted library/alpine:3.19 is not found as alpine:3.19.

A group is addressed exactly like a hosted repository, with the same host and the same repositories/ segment:

Terminal
docker pull your-org.mycloudrepo.io/repositories/team-registry/my-app:1.0.0

A typical arrangement is one address for developers and two repositories behind it: app-images holding what your team builds, and vendor-images holding third-party images you have vetted and pushed yourself. Group team-registry lists them in that order, and developers configure one host and one repository name.

Turn on Public Access in the repository’s settings (see Enabling Public Repository Access) and the repository’s images are served at the same address as when it is private. A pull that presents no credentials is served for a public Docker repository and refused for a private one. A push always needs credentials. Like any download by someone who is not signed in, an anonymous pull is not recorded in Latest activity or the audit log.

All Standard Settings apply.

View as Markdown