From 2c1379cca5c5436db2811c595fbe5f413d0074ad Mon Sep 17 00:00:00 2001
From: Henry Luetcke <hluetcke@ethz.ch>
Date: Wed, 7 Aug 2024 12:07:15 +0200
Subject: [PATCH] update section on sharing with Player scripts
---
RRP-User-Documentation.html | 53 ++++++++++++++++++++++++++++++++-----
rrp-docs.md | 13 +++++++--
2 files changed, 58 insertions(+), 8 deletions(-)
diff --git a/RRP-User-Documentation.html b/RRP-User-Documentation.html
index 5efcd80..5744316 100644
--- a/RRP-User-Documentation.html
+++ b/RRP-User-Documentation.html
@@ -384,11 +384,11 @@ and user credentials, then click <strong>Clone</strong>.</li>
bundles</h2>
<p>RRP projects can also be shared with other researchers (colleagues,
reviewers etc.) that are not registered users on the server. The only
-requirement for this is a computer with the <a href="https://www.docker.com/">Docker container engine</a> 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:</p>
+<strong>requirement is a computer with the <a href="https://www.docker.com/">Docker container engine</a></strong>
+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:</p>
<ol type="1">
<li>Switch to the Share tab of the RRP project and ensure the repository
is clean and up-to-date with the remote.</li>
@@ -406,7 +406,7 @@ macOS / Linux) or the <code class="sourceCode bash"><span class="ex">play.bat</s
on Windows. This will launch the JupyterLab interface in the default
browser.</li>
</ol>
-<p><strong>Some caveats for running Player bundles:</strong></p>
+<p><strong>Some caveats concerning running Player bundles:</strong></p>
<ol type="1">
<li>Player bundles have been tested successfully on different
combinations of OS and architectures, but <strong>there may be setups
@@ -420,5 +420,46 @@ the security warning that pops up, also select <em>Open</em>.</li>
</ol>
<h2 data-number="6.3" id="sharing-projects-with-player-scripts"><span class="header-section-number">6.3</span> Sharing projects with Player
scripts</h2>
+<p>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-users computer.</p>
+<p>To create a Player script, first export the required openBIS datasets
+to one of the research data repositories supported by openBIS (currently
+<a href="https://zenodo.org/">Zenodo</a> and <a href="https://www.research-collection.ethz.ch/">ETH Research
+Collection</a>). Please see the <a href="https://openbis.readthedocs.io/en/20.10.x/user-documentation/general-users/data-export.html">openBIS
+documentation</a> for details how to export data to repositories.
+Exported dataset permIDs are shown on the <strong>Share</strong> tab of
+the RRP project in the <strong>Player scipts</strong> section. Next,
+export the Docker image with the computational environment by clicking
+<em>Export image</em>. Once the export has completed and and the status
+of <em>Image exported</em> has changed to <em>Yes</em>, click
+<em>Generate player script</em> 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.</p>
+<p>To run the Player script on the recipient’s computer, ensure that <a href="https://www.docker.com/">Docker</a> is installed and running.
+Extract the zip-archive and execute either the <code class="sourceCode bash"><span class="ex">play</span></code> script (on
+macOS / Linux) or the <code class="sourceCode bash"><span class="ex">play.bat</span></code> / <code class="sourceCode bash"><span class="ex">play.ps1</span></code> scripts
+on Windows. This will launch the JupyterLab interface in the default
+browser.</p>
+<p><strong>Some caveats concerning running Player scripts:</strong></p>
+<ol type="1">
+<li>Player scripts have been tested successfully on different
+combinations of OS and architectures, but <strong>there may be setups
+that have not been tested</strong> and running Player scripts could
+potentially fail.</li>
+<li>If you execute the <code class="sourceCode bash"><span class="ex">play</span></code> script on
+macOS from the Finder, you may receive an error stating <em>“playâ€
+cannot be opened because it is from an unidentified developer</em>. To
+execute the script, right-click on it and then choose <em>Open</em>. In
+the security warning that pops up, also select <em>Open</em>.</li>
+<li>The code repository is <strong>NOT</strong> 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.</li>
+</ol>
</body>
</html>
diff --git a/rrp-docs.md b/rrp-docs.md
index cff8d92..be611c9 100644
--- a/rrp-docs.md
+++ b/rrp-docs.md
@@ -57,18 +57,27 @@ RRP projects can be shared with other users of the same server (e.g. fellow lab
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 for this is a computer with the [Docker container engine](https://www.docker.com/) 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:
+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](https://www.docker.com/)** 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](https://www.docker.com/) is installed and running. Extract the zip-archive and execute either the `play`{.bash} script (on macOS / Linux) or the `play.bat`{.bash} / `play.ps1`{.bash} scripts on Windows. This will launch the JupyterLab interface in the default browser.
-**Some caveats for running Player bundles:**
+**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`{.bash} 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*.
## 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-users computer.
+To create a Player script, first export the required openBIS datasets to one of the research data repositories supported by openBIS (currently [Zenodo](https://zenodo.org/) and [ETH Research Collection](https://www.research-collection.ethz.ch/)). Please see the [openBIS documentation](https://openbis.readthedocs.io/en/20.10.x/user-documentation/general-users/data-export.html) for details 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 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](https://www.docker.com/) is installed and running. Extract the zip-archive and execute either the `play`{.bash} script (on macOS / Linux) or the `play.bat`{.bash} / `play.ps1`{.bash} 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`{.bash} 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. 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.
--
GitLab