OCI Image Registries

It is common for users of Apptainer to use OCI registries as sources for their container images. Some registries require credentials to access certain images or even the registry itself. One method is 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.

Alternatively, users can supply credentials on a per-registry basis with the registry command.

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

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

$ apptainer registry list

URI                  SECURE?
docker://docker.com  ✓

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

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

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

$ apptainer registry list

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

Apptainer 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 their home directory.