Library API Registries

Overview

Apptainer enables users to use Library API Container Registries to push containers to a registry that was designed specifically for SIF images and pull SIF images created by others.

Apptainer does not have a default library service defined. If you want to use this you will probably need to first restore pre-Apptainer library behavior.

Many Library API registries will require authentication to perform operations like pushing container images or pulling potentially private container images. The remote command group governs the authentication for Library API registries. Check out the instructions for how to add and login with a remote endpoint.

Once you have authenticated, you are ready to push your container!

Pushing a Container

The apptainer push command will push a container to the container library with the given URL. Here’s an example of a typical push command:

$ apptainer push my-container.sif library://your-name/project-dir/my-container:latest

The :latest is the container tag. Tags are used to have different version of the same container.

Note

When pushing your container, there’s no need to add a .sif (Singularity Image Format) to the end of the container name, (like on your local machine), because all containers on the library are SIF containers.

Let’s assume you have your container (v1.0.1), and you want to push that container without deleting your :latest container, then you can add a version tag to that container, like so:

$ apptainer push my-container.sif library://your-name/project-dir/my-container:1.0.1

You can download the container with that tag by replacing the :latest, with the tagged container you want to download.

To set a description against the container image as you push it, use the -D flag introduced in Apptainer 3.7. This provides an alternative to setting the description via the web interface:

$ apptainer push -D "My alpine 3.11 container" alpine_3.11.sif library://myuser/examples/alpine:3.11
2.7MiB / 2.7MiB [=========================================================================] 100 % 1.1 MiB/s 0s

Library storage: using 13.24 MiB out of 11.00 GiB quota (0.1% used)
Container URL: https://cloud.example.com/library/myuser/examples/alpine

Note that when you push to a library that supports it, Apptainer will report your quota usage and the direct URL to view the container in your web browser.

Pulling a container

The apptainer pull command will download a container from an OCI Registry (docker://), Library API Registry (library://), and also Shub (shub://).

Note

When pulling from Docker, the container will automatically be converted to a SIF (Singularity Image Format) container.

Here’s a typical pull command:

$ apptainer pull file-out.sif library://alpine:latest

# or pull from docker:

$ apptainer pull file-out.sif docker://alpine:latest

Note

If there’s no tag after the container name, Apptainer automatically will pull the container with the :latest tag.

To pull a container with a specific tag, just add the tag to the library URL:

$ apptainer pull file-out.sif library://alpine:3.8

Of course, you can pull your own containers. Here’s what that will look like:

Pulling your own container

Pulling your own container is just like pulling from Github, Docker, etc…

$ apptainer pull out-file.sif library://your-name/project-dir/my-container:latest

# or use a different tag:

$ apptainer pull out-file.sif library://your-name/project-dir/my-container:1.0.1

Note

You don’t have to specify a output file, one will be created automatically, but it’s good practice to always specify your output file.

Verify/Sign your Container

Verify containers that you pull from the library, ensuring they are bit-for-bit reproductions of the original image.

Check out this page on how to: verify a container, making PGP key, and sign your own containers.

Searching the Library for Containers

To find interesting or useful containers in a library, you can open that library in your browser if that project supports a web GUI.

Alternatively, from the CLI you can use apptainer search <query>. This will search a library for container images matching <query>.

Building from a definition file:

This is our definition file. Let’s call it ubuntu.def:

bootstrap: library
from: ubuntu:22.04

%runscript
    echo "hello world from ubuntu container!"

Now, to build the container, use the --remote flag, and without sudo:

$ apptainer build --remote ubuntu.sif ubuntu.def

After building, you can test your container like so:

$ ./ubuntu.sif
hello world from ubuntu container!