[JOSS review] Installation instruction

Issue #11 resolved
Pi-Yueh Chuang created an issue

In a nutshell

Generally speaking, only the comment number 4 is a required modification for the JOSS review. Others are my suggestions.

1. The use of git@bitbucket.org:ocellarisproject/ocellaris.git in the git clone command

Using the SSH protocol to access the repo requires extra environment settings from users. I think it may not be a good idea to assume all users have Bitbucket account and have already set up SSH access. I'll suggest using https://bitbucket.org/ocellarisproject/ocellaris.git in the installation instruction.

2. Building a Singularity image locally requires root privilege

Building a Singularity image from scratch (i.e., from a Singularity file) requires root privilege. The instruction, however, does not mention this. I suggest following the common practice in the Linux community: specifying the privilege required for each shell command with a prefix like $ (regular user) or # (root).

Except building an image from scratch, other Singularity operations do not require root privilege. This includes pull and run. So I'll suggest you upload the Singularity image to some public registries like SingularityHub or Singularity Library and ask users to just pull and run the image. In this way, they won't have to deal with the privilege issue.

If uploading a Singularity image to a registry is not an option, then I'll suggest improving the instruction. For example, maybe detailing how to build an image on a machine that users have root privilege and transfer the image file to HPC systems. Or maybe mention that there are some online Singularity builders, and users without root privilege can utilize those online services.

3. The purpose of Docker image

It looks like the main purpose of the Docker image is for the CI tests only and is not ready for end-users. If this is true, then I think it does not have to be mentioned in the section of Installation using containers. I believe this will confuse readers. Instead, I think it's better to describe this Docker image in another new section explaining how Ocellaris utilizes the CI tests. Or maybe describing the Docker image in the section Installation using pip for those who want to use pip installation but don't want to deal with dependencies.

4. A clearly-stated list of dependencies

This is required by the JOSS review checklist. As it describes:

Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.

So even though the main installation method is through Singularity image, it's better to have a list describing each dependency and its version.

5. The use of pip3 in the section of Installation using pip

pip3 is not general to all use cases, especially for operating systems or environments that have only Python 3. For those systems or environments, they simply use pip to manage Python 3 packages because they don't have to distinguish between Python 2 and Python 3.

An example: when a user installs FEniCS through Anaconda following FEniCS's official instruction:

$ conda create -n fenicsproject -c conda-forge fenics
$ source activate fenicsproject
$ git clone https://bitbucket.org/ocellarisproject/ocellaris.git
$ cd ocellaris
$ pip3 install .

The user's shell will either find no pip3 or find the wrong pip3 (i.e., the system-wide one). For this example use case, only pip install . works.

By using pip3, you are assuming users use some specific systems/environments (for example, Ubuntu, or a fat Anaconda environment), which may not be true. I'm not saying using pip3 in the installation instruction is incorrect, what I'm saying is it will be nice to explicitly describe under what systems/environments the commands are guaranteed to be executed. So when users fail to execute a command, like pip3, they will know it's because they do not use the same system or environment setup as you do.

Comments (9)

  1. Tormod Landet

    Thanks for testing!

    1. Git URL changed to https://...
    2. Added "sudo ..." and uploaded the image to the Library. I have previously used SingularityHub, but stopped since they did not support Singularity 3.0. The new Sylabs Cloud Library worked perfectly, thanks for the hint!
    3. I split the Docker and Singularity info into separate sections and made it clear the Singularity is the recommended way (but Docker will also work for people who prefer that)
    4. Added list of dependencies, https://www.ocellaris.org/user_guide/install.html#id1 5) Changed to python3 -m pip ... to avoid this confusion.

    Thanks for all your helpful comments!

  2. Log in to comment