Which Document page:

UserDoc page

Expected results:

Successful compile of the epub format

Actual results:

System complains of 'mconfig' being missing. Only way to fix was to copy the 'working' makefile from admin docs, and type

make epub

Update the Copyright messages here as in apptainer/apptainer#190.

I found that in order for cgroups v2 to work I had to enable it on el8 according to these instructions. It would be good to mention that on the cgroups page where it mentions configuraing systemd to delegate to non-root users.

There's very little mention of nesting apptainer sessions in the docs. Add a section that talks about what can and can't be done and what is inherited by the inner session.

The "a" or "A" before "{Project}" needs to be "an" or "An" for correct English.

In order to keep our project-independence, I suggest adding two more replacements "{AProject}" and "{aProject}" to use for those cases.

Document APPTAINER_CONFIGDIR, APPTAINER_SILENT, APPTAINER_QUIET, APPTAINER_VERBOSE, and APPTAINER_NOCOLOR.

There are some third-party references, like Singularityware, that needs to be addressed as well replaced. For that, we should decide how Apptainer project will handle not only the references along the docs, but how to play around when it comes to operation side of those environments.

There are some refs, like the one in the final section of GPU "examples" that we should recreate or find any substitute,

Replace the APPTAINER prefixes introduced in #22 with a new replacement variable {ENVPREFIX}.

Using {Singularity} as a replacement variable for the project name isn't generic enough, so change it to {Project}.

The APPTAINER_SHARENS environment variable, associated with the --sharens option, is missing from the appendix.

In reference to
apptainer/apptainer#517

The Apptainer INSTALL.md refers to installation.html here as a place for instructions to install from EPEL but they are missing.

Document the fact that $APPTAINER_BIND is processed before $APPTAINER_BINDPATH, because the order matters with binding.

According to @DrDaveD:

If the user inside the container is fake root, /root is the user’s home directory

In other words, there is an undocumented bind mount from /home/currentuser into /root (if I understand correctly), which is unrelated to the standard mount home behaviour.

Ideally this would be documented.

In pr #1, publishing from this repository was disabled. Re-enable it such that the documentation is pushed to https://apptainer.org/docs/user (i.e., not to https://aptainer.org/user-docs since that is written by https://github.com/apptainer/singularity-userdocs).

Document the APPTAINER_MESSAGELEVEL environment variable added in apptainer-1.2.2.

Document using %post -c to run a different shell in a definition file. Does it work also on other sections? The document talks about using #! on the first line of some other sections; why is the %post section different?

This should just be a pass to rename environment variables to have the APPTAINER_ and APPTAINERENV_ prefixes

The codeblocks used inside this project do not use a search and replace strategy at generation time like {Singularity} provides, rename the application name in CLI examples.

This should document:

• Environment variable parsing priority
• Potential warning messages that can be encountered

Which Document page:

https://github.com/apptainer/apptainer-userdocs/blob/main/definition_files.rst

As the PR is merged
apptainer/apptainer#1356

We also need to add changes to apptainer user docs.

Targeting at v1.2.0

DMTCP-based checkpointing needs to be documented.

At least the security page discussion will need to change, check the rest. Also check the admindocs to see if changes are needed there.

This is no longer a supported API in apptainer

Which Document page:

On what page is the problem?

https://apptainer.org/docs/user/1.2/docker_and_oci.html#docker-cli-authentication

Expected results:

According to this github issue apptainer/singularity#2792 (comment) and my experience with apptainer version 1.2.2 credentials helpers DO work.

So the docs should mention that via something along the lines of:

Apptainer can read credentials from external Docker credential helpers defined under the credHelpers in ~/.docker/config.json.

Actual results:

The docs currently say:

Apptainer can only read credentials stored directly in ~/.docker/config.json. It cannot read credentials from external Docker credential helpers.

Document new APPTAINER_ENCRYPTION_PEM_DATA environment variable.

Hi all,

You have been bringing in some 2021 changes from the Sylabs documentation repositories, e.g. #33

Your LICENSE file is only listing copyright for Sylabs up to 2020, not 2021.

Please could you ensure on admindocs and userdocs that the copyright attribution matches the years for which you have brought content over from the Sylabs repositories.

Thanks!

In general we should aim for these sections of documentation to be vendor neutral

The intro on the gpu.html page talks about using host libraries from old operating systems in containers "regardless" of the mismatch between host and container operating systems. There is a limit, however, if the libc library on the host and in the container are of very different vintage. The intro should be more clear about that limitation.

Functionality corresponding to the following sylabs userdocs PRs have been imported into apptainer and so the documentation should probably also be imported:

• sylabs/singularity-userdocs#174
• sylabs/singularity-userdocs#175
• sylabs/singularity-userdocs#194
• sylabs/singularity-userdocs#195 (also asked for in #223)
• sylabs/singularity-userdocs#198
• sylabs/singularity-userdocs#207
• sylabs/singularity-userdocs#209
• sylabs/singularity-userdocs#210
• sylabs/singularity-userdocs#212
• sylabs/singularity-userdocs#213
• sylabs/singularity-userdocs#215

In addition, look at these to see if there are improvements compared to what we already have:

• sylabs/singularity-userdocs#199
• sylabs/singularity-userdocs#200
• sylabs/singularity-userdocs#205

Which Document page:

https://apptainer.org/docs/user/main/build_a_container.html?highlight=library

Expected results:

The apptainer user docs refer to the "library" container resource, which I understand to have been removed from apptainer. (The "shub" resource might also be removed.)

Actual results:

$ apptainer --version
apptainer version 1.0.0~rc.2-1.fc35

$ apptainer pull library://library/default/rockylinux
FATAL:   Unable to get library client configuration: remote has no library client

Doing 'make html' or 'make epub' prints a bunch of warnings that are currently ignored. They can also be seen in CI runs. Fix the warnings.

Which Document page:

On what page is the problem?
encryption.rst

Expected results:

What are you expecting to see?
Needing changes to encrypted image build and execution.

Actual results:

Missing now.

In order to greatly simplify the task of renaming to Apptainer, first remove all references to specific version numbers in this repository. Remove descriptions of older behavior, and for anything that describes behavior starting at a certain version number such as "Since version 3.6 ..." just remove that reference while leaving the rest of the behavior description because it still applies to the current version. Only leave the description of the current behavior; people who want to know the older behavior can look at the archived versions of the documentation.

Commands making any reference to Singularity should be updated to apptainer

Which Document page:

Apptainer User Guide - Instances - Running Services - Starting Instances

Expected results:

A note about requiring root on apptainer instance list if in setuid mode.

Actual results:

If apptainer is used in setuid mode, then instances, although started by $USER, are managed by root. Hence apptainer instance list will show an empty list. The current note on the document page linked above informs that:

"[...] if you use sudo to start an instance as root, you will need to use sudo for all commands managing that instance".

An additional note informing about the same requirement for setuid mode might help avoid confusion.

Rename singularity_and_docker.rst to docker_and_oci.rst. Rename pygments_singularity.py to pygments_definition.py. There's a reference to cli/singularity.rst in Makefile but I don't think it is used anywhere, it can be deleted.

Using Apptainer with --overlay on an MPI applications I got into the issue that apptainer is not able to start more than one instance with overlay reasonably.
I took a look into the userdocs but couldn't find any hint how to make overlay images mounted in read-only mode to get rid of this issue. Then I found the solution in apptainer/singularity#5577 to use --overlay overlay.img:ro.

Is using :ro a feature you do not want to support officially or is it simply missing in the user docs?
If it simply missing I can do a PR if I am aked for.

Which Document page:

On what page is the problem?

https://apptainer.org/docs/user/main/persistent_overlays.html

or

https://github.com/apptainer/apptainer-userdocs/blob/main/persistent_overlays.rst

Expected results:

I would like to use overlay, but if I copy line 104, check the actual results. This is with apptainer version 1.0.3-1.el8

Actual results:

apptainer overlay create --fakeroot --size 1024 overlay.img
Error for command "create": unknown flag: --fakeroot

Options for create command:

      --create-dir strings   directory to create as part of the overlay layout
  -h, --help                 help for create
  -s, --size int             size of the EXT3 writable overlay in MiB (default 64)

Run 'apptainer --help' for more detailed usage information.

Which Document page:

Quck Start

Expected results:

I'm used to Docker, where there are no sif files to specify. One can just run docker run <name_of_image>. AFAIK, apptainer run requires the user to specify the path to the sif file.

All of the apptainer docs seem to assume that the sif file is in the user's working directory (e.g., apptainer run lolcow_latest.sif). There doesn't seem to be any clear docs on whether/how one can set a PATH-like variable that defines where apptainer run will look for sif files, if the sif file is not in the user's working directory. For example:

# set the location of 
APPTAINER_SIF_DIR=${HOME}/apptainer_sif_files/

# execute `apptainer run` from any location
apptainer run lolcow_latest.sif 

# lolcow_latest.sif is not in the working directory, so `apptainer run` looks in $APPTAINER_SIF_DIR

If this is not possible, it would help to explicitly state that one must always provide the path to the sif file... or create some sort of custom alias/function to set the directory where all sif files are located (if the specified sif file path does not exist).

Actual results:

It would be helpful if the user could organize all sif files in >=1 specific locations (repositories) and easily call any one of these sif files without the need to provide the full to the sif file or create a custom setup (e.g., an alias or function).

In general we should aim for this section to be vendor neutral

This relates mostly to the "User Namespaces and Fakeroot" page. I found it fairly confusing because apptainer has so many modular features, each of which requires different levels of permissions and dependent software, that in turn enable different capabilities in apptainer. In theory this could be expanded to talk about FUSE filesystems etc as well.

The motivation for this is helping sysadmins determine which features they can enable "for free" (ie without security risks) e.g. fakeroot, and which ones can be skipped. e.g. the setuid flag is possibly not needed on newer Linux kernels.

I think it might be helpful to present this information as a collection of paragraphs, one for each capability, that describe this information in a structure way. Now I don't actually have all the info to write this because I still don't fully understand everything, but here's an example:

Name: Fakeroot binary
How to Enable Install fakeroot command (can be compiled from scratch or installed as a package)
Required Privileges: None (any user can compile fakeroot)
Security risks: None
Enables: The use of sudo inside apptainer, for example sudo apt install or sudo make install. This allows the use of many standard installation mechanisms, which can make building containers much easier

Name: Setuid Flag
How to Enable Install apptainer-suid package instead of apptainer
Required Privileges: Root
Security risks: Potentially
Enables: Allows apptainer to run on old Linux kernels that don't support user namespaces

Name: subuid Mappings
How to Enable: The root user can customize /etc/subuid and /etc/subgid
Required Privileges: Root
Security risks: No (?)
Enables: Allows apptainer to map multiple users inside the container to multiple users outside the container. This extends the default behaviour whereby the running user outside the container is mapped to root inside the container.

Details are captured here:

apptainer/apptainer#1812

Docs has some references to Google Group. In the upcoming meetings or in chat, decide what to do on this regard.

Favicon and logo image can be found: https://github.com/apptainer/apptainer.org/tree/master/src/images

Which Document page:

https://apptainer.org/docs/user/1.1/quick_start.html

Expected results:

I'd expect to see it link to
https://github.com/apptainer/apptainer/blob/release-1.1/INSTALL.md

Actual results:

By means of this code:

It actually links to
https://github.com/apptainer/apptainer/blob/1.1/INSTALL.md
But that page (branch) does not exist

I notice that this repo uses 1.0, 1.1 for branch names - maybe it should use same convention, release-1.0, release-1.1?

While updating automated / narrowly scoped scripts
EricCousineau-TRI/repro@f50c60d

Which Document page:

https://apptainer.org/docs/user/main/signNverify.html#verifying-containers-from-the-remote-sources

On what page is the problem?

"Verifying containers from the remote sources"

Issue

To use this feature with SIF images that you pull from container libraries or OCI registries via oras://.

This is a sentence fragment.