Sharing Projects

Sharing a project

RRP offers several options for sharing a project (code, data, computational environment) with others. These options are available under the Share tab of the project.

Important: before a project can be shared with RRP, the repository must be in clean state. This means that any changes have to be commited and pushed to the remote before a project can be shared. RRP indicates if this is the case in the Repository status section of the Share tab.

Sharing projects with users of the same server with share IDs

RRP projects can be shared with other users of the same server (e.g. fellow lab members, PI etc.):

  1. Switch to the Share tab of the RRP project. Any existing share identifiers are listed under Share identifiers.
  2. To create a new share identifier, enter a short description and then select Create share identifier.
  3. If successfull, the new share identifier will be listed above. Share it with colleagues either by mail or chat.
  4. To create a new project from a share identifier, select the + button next to Your projects and click “Create new project from Share identifier”. Enter the identifier and user credentials, then click Clone.

Sharing projects with Player bundles

RRP projects can also be shared with other researchers (colleagues, reviewers etc.) that are not registered users on the server. The only requirement is a computer with the Docker container engine installed and running. For small to medium-sized projects (up to a few GBs), RRP Player bundles can be created that contain the whole project (code, data, computational environment) in a single file. To create a Player bundle:

  1. Switch to the Share tab of the RRP project and ensure the repository is clean and up-to-date with the remote.
  2. In the Create new player bundle section, enter a short description and click Create player bundle. The creation of new player bundles may take a few minutes (depending on project size) and status is indicated above in the list of Player bundles. Once the status has switched from in process to complete, the Player bundle file can be downloaded by selecting the download icon. The downloaded zip-file can be shared with other researchers, e.g. by standard file-sharing services.
  3. To run the Player bundle on the recipient’s computer, ensure that Docker is installed and running. Extract the zip-archive and execute either the play script (on macOS / Linux) or the play.bat / play.ps1 script on Windows. This will launch the JupyterLab interface in the default browser.

Some caveats concerning running Player bundles:

  1. Player bundles have been tested successfully on different combinations of OS and architectures, but there may be setups that have not been tested and running Player bundles could potentially fail.
  2. If you execute the play script on macOS from Finder, you may receive an error stating "play" cannot be opened because it is from an unidentified developer. To execute the script, right-click on it and then choose Open. In the security warning that pops up, also select Open.
  3. On Windows, the script may be blocked due to restrictive execution policy. Use the Unblock-File cmdlet to remove the block.

Sharing projects with Player scripts

Player bundles will likely be inefficient for sharing very large RRP projects, i.e. exceeding several GBs. In these cases, it is recommended to upload the datasets to a research data repository supported by openBIS. Furthermore, the computational environment (Docker image) should be exported to a container registry, such as DockerHub. RRP Player scripts can then be used to download Docker images and research data directly from the end-user’s computer.

To create a Player script, first export the required openBIS datasets to one of the research data repositories supported by openBIS (currently Zenodo and ETH Research Collection). Please see the openBIS documentation for details on how to export data to repositories. Exported dataset permIDs are shown on the Share tab of the RRP project in the Player scipts section. Next, export the Docker image with the computational environment by clicking Export image. Once the export has completed and the status of Image exported has changed to Yes, click Generate player script and download the zip-archive, which will only be a few KBs in size. The downloaded zip-file can be shared with other researchers, e.g. by standard file-sharing services or e-mail.

To run the Player script on the recipient’s computer, ensure that Docker is installed and running. Extract the zip-archive and execute either the play script (on macOS / Linux) or the play.bat / play.ps1 scripts on Windows. This will launch the JupyterLab interface in the default browser.

Some caveats concerning running Player scripts:

  1. Player scripts have been tested successfully on different combinations of OS and architectures, but there may be setups that have not been tested and running Player scripts could potentially fail.
  2. If you execute the play script on macOS from the Finder, you may receive an error stating “play” cannot be opened because it is from an unidentified developer. To execute the script, right-click on it and then choose Open. In the security warning that pops up, also select Open.
  3. On Windows, the script may be blocked due to restrictive execution policy. Use the Unblock-File cmdlet to remove the block.
  4. The code repository is NOT included in the Player script but will be cloned directly from the Git remote upon script execution. For private repositories, user credentials must thus be provided.