Edit This Page

This tutorial takes a container image from your machine into a Docker repository of your Repsy Open Source instance and back. It complements Publishing a Docker Image and Installing a Docker Image from Registry, which show the same commands in short.

Prerequisites

• A Docker repository on your Repsy Open Source instance, see Creating a Private Docker Registry.
• The Docker CLI, and an image to push. The examples use hello-world.
• A credential: your username and password, or a deploy token. A deploy token goes into the password prompt and needs the Read/Write access type to push; the username can be any value.
• A way for Docker to reach the instance, see HTTP and HTTPS. On the machine that runs Repsy, localhost:9090 works without further setup.

How Images Are Named

An image reference in Repsy has this form:

<your-repsy-host>/<repo-name>/<image-name>:<image-tag>

An image is created by the first push to its name; you do not create it beforehand. Docker only accepts lower-case references, so use lower-case names.

docker login <your-repsy-host>

echo "$REPSY_DEPLOY_TOKEN" | docker login <your-repsy-host> -u <username> --password-stdin

docker pull hello-world
docker tag hello-world <your-repsy-host>/<repo-name>/hello-world:1.0

docker push <your-repsy-host>/<repo-name>/hello-world:1.0

docker pull <your-repsy-host>/<repo-name>/hello-world:1.0
docker pull <your-repsy-host>/<repo-name>/hello-world@<digest>

docker pull --platform <platform> <your-repsy-host>/<repo-name>/<image-name>:<image-tag>

Private and Public Repositories

Pushing always needs credentials, also for a public repository. Deleting a manifest or a tag through the registry API needs the ADMIN role, and a deploy token is never allowed to do it. See Managing Docker Tags and Manifests. A deploy token is checked when Docker logs in and again for every request; a token of another repository or a Read Only token is therefore accepted by docker login and refused at the first docker push or docker pull it cannot do. See Understanding Public vs Private.

What a Push Stores

A push is a sequence of requests, and it helps to know what Repsy does with them:

• Layers are stored per repository and by digest. Before it uploads a layer, the client asks Repsy whether it has it, and uploads only the layers that are missing. Uploading a layer that the repository already has is accepted and stores nothing twice. Repsy checks the digest of every layer against the bytes it received and refuses a layer that does not match with 400 (DIGEST_INVALID). Repsy does not implement cross-repository blob mounts, so the same layer pushed to two repositories is uploaded to both.
• The manifest comes last. The manifest names the layers and the config of the image. Repsy refuses a manifest that names a layer it does not have with 404 (MANIFEST_BLOB_UNKNOWN), and an image config without an os or an architecture with 400 (MANIFEST_INVALID). It accepts Docker image manifests, Docker manifest lists, OCI image manifests and OCI image indexes.
• A refused or failed push leaves no image behind, but it can leave layers. If the manifest is refused, the layers that were already uploaded stay in the repository without any manifest that uses them. They are the orphan layers that Managing Docker Tags and Manifests explains how to delete. An upload that was started and never finished is deleted by Repsy after 24 hours by default (ABANDONED_UPLOAD_TTL, see the Configuration Reference).
• A tag moves when you push it again. A repository has the setting Package Override, Allow by default. With Allow, pushing an existing tag with a different image moves the tag to the new image, and the old image stays pullable by its digest. With Deny, Repsy refuses that push with 403 (DENIED, message You cannot override a version.) and the tag is unchanged. Pushing the image a tag already points at changes nothing and is accepted in both cases, and so is pushing a new tag.
• Digests. Every image is stored under its sha256 digest, and Repsy also records its sha512 digest, so a client can reference it by either.

HTTP and HTTPS

Docker talks to a registry over HTTPS. The one exception is a registry on localhost (and the other loopback addresses), where Docker accepts plain HTTP without configuration. Repsy listens on plain HTTP on port 9090 by default, so:

• On the machine that runs Repsy, localhost:9090 works as it is. This is what Quick Start uses.
• From any other machine, use HTTPS. Either turn on the HTTPS port of the repository port of Repsy (REPO_SSL_ENABLED, port 9443, see Configuration Reference), or put a reverse proxy with a certificate in front of it and set REPO_BASE_URL to its address. Docker must trust the certificate: a certificate from a public authority works, and for one from your own authority you place its CA certificate in /etc/docker/certs.d/<your-repsy-host>/ca.crt on the Docker host (see the Docker documentation on certificates). The name of the directory has to include the port, for example /etc/docker/certs.d/repo.example.com:9443/ca.crt: a directory named repo.example.com is not used for repo.example.com:9443. Docker reads the file with the next command, so the daemon needs no restart.
• Behind a reverse proxy, the proxy has to forward the Host, X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port headers. Repsy builds the address of its token endpoint, which docker login is sent to, from the request it received. Without these headers the address names the internal scheme and port, and docker login fails.

The ports of a default installation are described in Ports and Repository URLs.

Troubleshooting

Repsy also sends the identifier of the error in the JSON body that the registry API defines (errors, with a code, a message and a detail). Docker prints the message.

Installing a Docker Image from Registry Using crane and Other OCI Tools

Was this page helpful?

Yes No