OCI Image Registries

It is common for users of SingularityCE to use OCI registries as sources for their container images. Some registries require credentials to access certain images or even the registry itself. Previously, the only method in SingularityCE to supply credentials to registries was to supply credentials for each command or set environment variables to contain the credentials for a single registry. See Authentication via Interactive Login and Authentication via Environment Variables.

Starting with SingularityCE 4.0, users can supply credentials on a per-registry basis with the registry command.

Note

In versions of SingularityCE starting from 3.7 but before 4.0, the functionality described here was grouped together with remote endpoint management under the remote command group. Beginning with version 4.0, this functionality has been given its own top-level command group, registry.

Users can login to an OCI registry with the registry login command by specifying a docker:// prefix to the registry hostname:

$ singularity registry login --username myuser docker://docker.com
Password / Token:
INFO:    Token stored in /home/myuser/.singularity/remote.yaml

$ singularity registry list

URI                  SECURE?
docker://docker.com  ✓

SingularityCE will automatically supply the configured credentials when interacting with DockerHub. The checkmark in the SECURE? column indicates that SingularityCE will use TLS when communicating with the registry.

A user can be logged-in to multiple OCI registries at the same time:

$ singularity registry login --username myuser docker://registry.example.com
Password / Token:
INFO:    Token stored in /home/myuser/.singularity/remote.yaml

$ singularity registry list

URI                            SECURE?
docker://docker.com            ✓
docker://registry.example.com  ✓

SingularityCE will supply the correct credentials for the registry based on the hostname used, whenever one of the following commands is used with a docker:// or oras:// URI:

pull, push, build, exec, shell, run, instance

Note

It is important for users to be aware that the registry login command will store the supplied credentials or tokens unencrypted in your home directory.