Deployed f0c457a with MkDocs version: 1.6.1

safe-haven-services/open-ondemand/apps/jupyter-app/index.html

@@ -2701,6 +2701,30 @@
     </span>
   </a>
 
+    <nav class="md-nav" aria-label="Installing Python packages">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#install-packages-within-a-mntjupyter_host-subdirectory" class="md-nav__link">
+    <span class="md-ellipsis">
+      Install packages within a /mnt/jupyter_host subdirectory
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#create-a-virtual-environment-within-mntjupyter_host" class="md-nav__link">
+    <span class="md-ellipsis">
+      Create a virtual environment within /mnt/jupyter_host
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
         <li class="md-nav__item">
@@ -2826,7 +2850,7 @@ <h2 id="sharing-files-between-the-back-end-and-jupyterlab-and-persisting-state-b
 <p>The app also creates a <code>$HOME/.local/share/ondemand/apps/jupyter_app/</code> in your home directory on the back-end and mounts this into JupyterLab at <code>/mnt/jupyter_host</code>. If you create virtual environments and/or install Python packages into <code>/mnt/jupyter_host</code> when using JupyterLab, then these will be available to you when you run the app in future (each run of the app creates a new container, and this mount allows for state to be persisted between runs).</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>It is recommended that this directory be used for configuration files, code, scripts and Python packages only. It should <strong>not</strong> be used for data.</p>
+<p>It is recommended that <code>/mnt/jupyter_host</code> be used for configuration files, code, scripts and Python packages only. It should <strong>not</strong> be used for data.</p>
 </div>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
@@ -2848,15 +2872,77 @@ <h2 id="accessing-files-outside-the-scope-of-your-home-directory">Accessing file
 <div class="admonition tip">
 <p class="admonition-title">Tip</p>
 <p>A workaround to make these directories visible via JupyterLab file browsers is to create symbolic links from your home directory, within the container, to these directories. This can be done within a JupyterLab Terminal as follows:</p>
-<div class="highlight"><pre><span></span><code><span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/safe_data/
-<span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/safe_outputs/
-<span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/scratch/
-<span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/mnt/jupyter_host<span class="w"> </span>lib
+<div class="highlight"><pre><span></span><code>ln<span class="w"> </span>-s<span class="w"> </span>/safe_data/
+ln<span class="w"> </span>-s<span class="w"> </span>/safe_outputs/
+ln<span class="w"> </span>-s<span class="w"> </span>/scratch/
+ln<span class="w"> </span>-s<span class="w"> </span>/mnt/jupyter_host<span class="w"> </span>lib
 </code></pre></div>
 </div>
 <hr />
 <h2 id="installing-python-packages">Installing Python packages</h2>
-<p>JupyterLab is configured with your web proxy environment variables so you can install packages from PyPI when using JupyterLab. It is recommended that you create virtual environments and/or install Python packages into <code>/mnt/jupyter_host</code> so that you can reuse these the next time you run the app on the same back-end.</p>
+<p>JupyterLab is configured with your web proxy environment variables so you can install packages from PyPI when using JupyterLab. It is recommended that you install Python packages and/or create virtual environments within <code>/mnt/jupyter_host</code> so that you can reuse these the next time you run the app on the same back-end.</p>
+<p>There are a number of ways you can use such a directory within JupyterLab. Two examples are as follows. Python and JupyterLab resources online may suggest others.</p>
+<h3 id="install-packages-within-a-mntjupyter_host-subdirectory">Install packages within a <code>/mnt/jupyter_host</code> subdirectory</h3>
+<p>Install packages within a <code>/mnt/jupyter_host</code> subdirectory. For example:</p>
+<ol>
+<li>Select <strong>Launcher</strong>, <strong>Terminal</strong>.</li>
+<li>
+<p>Create directory for packages:</p>
+<div class="highlight"><pre><span></span><code>mkdir<span class="w"> </span>-t<span class="w"> </span>/mnt/jupyter_host/mypips
+</code></pre></div>
+</li>
+<li>
+<p>Install package:</p>
+<div class="highlight"><pre><span></span><code>pip<span class="w"> </span>install<span class="w"> </span>-t<span class="w"> </span>/mnt/jupyter_host/mypips<span class="w"> </span>PACKAGE_NAME
+</code></pre></div>
+</li>
+</ol>
+<p>Any Python code that needs the packages needs to include the path to the subdirectory. For example:</p>
+<div class="highlight"><pre><span></span><code><span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
+<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;/mnt/jupyter_host/mypips&#39;</span><span class="p">)</span>
+<span class="kn">import</span><span class="w"> </span><span class="nn">PACKAGE_NAME</span>
+</code></pre></div>
+<p>The subdirectory and packages will be persisted on the back-end upon which the app runs. For example:</p>
+<div class="highlight"><pre><span></span><code>$<span class="w"> </span>ls<span class="w"> </span><span class="nv">$HOME</span>/.local/share/ondemand/apps/jupyter_app/
+mypips
+$<span class="w"> </span>ls<span class="w"> </span><span class="nv">$HOME</span>/.local/share/ondemand/apps/jupyter_app/mypips/
+...
+PACKAGE_NAME
+...
+</code></pre></div>
+<h3 id="create-a-virtual-environment-within-mntjupyter_host">Create a virtual environment within <code>/mnt/jupyter_host</code></h3>
+<p>Create a virtual environment within <code>/mnt/jupyter_host</code> and install packages into that virtual environment. For example:</p>
+<ol>
+<li>Select <strong>Launcher</strong>, <strong>Terminal</strong>.</li>
+<li>
+<p>Create and activate a Python virtual environment:</p>
+<div class="highlight"><pre><span></span><code>python<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>/mnt/jupyter_host/my-venv
+<span class="nb">source</span><span class="w"> </span>/mnt/jupyter_host/my-venv/bin/activate
+</code></pre></div>
+</li>
+<li>
+<p>Install package into virtual environment:</p>
+<div class="highlight"><pre><span></span><code>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>PACKAGE_NAME
+</code></pre></div>
+</li>
+<li>
+<p>Register the virtual environment with JupyterLab, to create new IPython kernels to provide access to the virtual environment within JupyterLab Notebook and Console sessions:</p>
+<div class="highlight"><pre><span></span><code>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>ipykernel
+python<span class="w"> </span>-m<span class="w"> </span>ipykernel<span class="w"> </span>install<span class="w"> </span>--user<span class="w"> </span>--name<span class="w"> </span>py3-ipykernel-my-venv<span class="w"> </span>--display-name<span class="w"> </span><span class="s1">&#39;Python3 (ipykernel my-venv)&#39;</span>
+</code></pre></div>
+</li>
+</ol>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The next time you run this app you will need to activate the virtual environment and recreate the kernels within a JupyterLab Terminal:</p>
+<div class="highlight"><pre><span></span><code><span class="nb">source</span><span class="w"> </span>/mnt/jupyter_host/my-venv/bin/activate
+python<span class="w"> </span>-m<span class="w"> </span>ipykernel<span class="w"> </span>install<span class="w"> </span>--user<span class="w"> </span>--name<span class="w"> </span>py3-ipykernel-my-venv<span class="w"> </span>--display-name<span class="w"> </span><span class="s1">&#39;Python3 (ipykernel my-venv)&#39;</span>
+</code></pre></div>
+</div>
+<p>The virtual environment and its contents will be persisted on the back-end upon which the app runs. For example:</p>
+<div class="highlight"><pre><span></span><code>$<span class="w"> </span>ls<span class="w"> </span>.local/share/ondemand/apps/jupyter_app/
+my-venv/
+</code></pre></div>
 <hr />
 <h2 id="view-job-files">View job files</h2>
 <p>On a job's job card, click the <strong>Session ID</strong> link to open the <a href="../../files/">File Manager</a>, pointing at the job context directory for the job on the Open OnDemand VM.</p>

safe-haven-services/open-ondemand/apps/jupyter-os-app/index.html

@@ -2692,6 +2692,30 @@
     </span>
   </a>
 
+    <nav class="md-nav" aria-label="Installing Python packages">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#install-packages-within-your-home-directory" class="md-nav__link">
+    <span class="md-ellipsis">
+      Install packages within your home directory
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#create-a-virtual-environment-within-your-home-directory" class="md-nav__link">
+    <span class="md-ellipsis">
+      Create a virtual environment within your home directory
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
         <li class="md-nav__item">
@@ -2821,12 +2845,56 @@ <h2 id="accessing-files-outside-the-scope-of-your-home-directory">Accessing file
 <div class="admonition tip">
 <p class="admonition-title">Tip</p>
 <p>A workaround to make this directory visible via JupyterLab file browsers is to create symbolic links from your home directory to this directory. This can be done within a JupyterLab Terminal as follows:</p>
-<div class="highlight"><pre><span></span><code><span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/safe_data/PROJECT_SUBDIRECTORY<span class="w"> </span>safe_data
+<div class="highlight"><pre><span></span><code>ln<span class="w"> </span>-s<span class="w"> </span>/safe_data/PROJECT_SUBDIRECTORY<span class="w"> </span>safe_data
 </code></pre></div>
 </div>
 <hr />
 <h2 id="installing-python-packages">Installing Python packages</h2>
 <p>JupyterLab is configured with your web proxy environment variables so you can install packages from PyPI when using JupyterLab.</p>
+<p>If installing packages you may need to install these within your home directory. Two examples are as follows. Python and JupyterLab resources online may suggest others.</p>
+<h3 id="install-packages-within-your-home-directory">Install packages within your home directory</h3>
+<p>Install packages within a subdirectory of your home directory. For example:</p>
+<ol>
+<li>Select <strong>Launcher</strong>, <strong>Terminal</strong>.</li>
+<li>
+<p>Create directory for packages:</p>
+<div class="highlight"><pre><span></span><code>mkdir<span class="w"> </span>-t<span class="w"> </span>mypips
+</code></pre></div>
+</li>
+<li>
+<p>Install package:</p>
+<div class="highlight"><pre><span></span><code>pip<span class="w"> </span>install<span class="w"> </span>-t<span class="w"> </span>mypips<span class="w"> </span>PACKAGE_NAME
+</code></pre></div>
+</li>
+</ol>
+<p>Any Python code that needs the packages needs to include the path to the subdirectory. For example:</p>
+<div class="highlight"><pre><span></span><code><span class="kn">import</span><span class="w"> </span><span class="nn">os</span>
+<span class="kn">import</span><span class="w"> </span><span class="nn">sys</span>
+<span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">expanduser</span><span class="p">(</span><span class="s1">&#39;~&#39;</span><span class="p">),</span> <span class="s1">&#39;mypips&#39;</span><span class="p">))</span>
+<span class="kn">import</span><span class="w"> </span><span class="nn">PACKAGE_NAME</span>
+</code></pre></div>
+<h3 id="create-a-virtual-environment-within-your-home-directory">Create a virtual environment within your home directory</h3>
+<p>Create a virtual environment within your home directory and install packages into that virtual environment. For example:</p>
+<ol>
+<li>Select <strong>Launcher</strong>, <strong>Terminal</strong>.</li>
+<li>
+<p>Create and activate a Python virtual environment:</p>
+<div class="highlight"><pre><span></span><code>python3<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span>my-venv
+<span class="nb">source</span><span class="w"> </span>my-venv/bin/activate
+</code></pre></div>
+</li>
+<li>
+<p>Install package into virtual environment:</p>
+<div class="highlight"><pre><span></span><code>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>PACKAGE_NAME
+</code></pre></div>
+</li>
+<li>
+<p>Register the virtual environment with JupyterLab, to create new IPython kernels to provide access to the virtual environment within JupyterLab Notebook and Console sessions:</p>
+<div class="highlight"><pre><span></span><code>python<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>ipykernel
+python<span class="w"> </span>-m<span class="w"> </span>ipykernel<span class="w"> </span>install<span class="w"> </span>--user<span class="w"> </span>--name<span class="w"> </span>py3-ipykernel-my-venv<span class="w"> </span>--display-name<span class="w"> </span><span class="s1">&#39;Python3 (ipykernel my-venv)&#39;</span>
+</code></pre></div>
+</li>
+</ol>
 <hr />
 <h2 id="view-job-files">View job files</h2>
 <p>On a job's job card, click the <strong>Session ID</strong> link to open the <a href="../../files/">File Manager</a>, pointing at the job context directory for the job on the Open OnDemand VM.</p>

safe-haven-services/open-ondemand/apps/rstudio-app/index.html

@@ -2701,6 +2701,21 @@
     </span>
   </a>
 
+    <nav class="md-nav" aria-label="Installing R packages">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#install-packages-within-mntrstudio_host" class="md-nav__link">
+    <span class="md-ellipsis">
+      Install packages within /mnt/rstudio_host
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
         <li class="md-nav__item">
@@ -2831,7 +2846,7 @@ <h2 id="sharing-files-between-the-back-end-and-rstudio-server-and-persisting-sta
 <p>The app also creates a <code>$HOME/.local/share/ondemand/apps/rstudio_app/</code> in your home directory on the back-end and mounts this into RStudio Server at <code>/mnt/rstudio_host</code>. If you install R packages into <code>/mnt/rstudio_host</code> when using RStudio Server, then these will be available to you when you run the app in future (each run of the app creates a new container, and this mount allows for state to be persisted between runs).</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>It is recommended that this directory be used for configuration files, code, scripts and R packages only. It should <strong>not</strong> be used for data.</p>
+<p>It is recommended that <code>/mnt/rstudio_host</code> be used for configuration files, code, scripts and R packages only. It should <strong>not</strong> be used for data.</p>
 </div>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
@@ -2854,15 +2869,30 @@ <h2 id="accessing-files-outside-the-scope-of-your-home-directory">Accessing file
 <div class="admonition tip">
 <p class="admonition-title">Tip</p>
 <p>A workaround to make this directories visible via RStudio Server file browsers is to create symbolic links from your home directory, within the container, to these directories. This can be done within an RStudio Server Terminal as follows:</p>
-<div class="highlight"><pre><span></span><code><span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/safe_data/
-<span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/safe_outputs/
-<span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/scratch/
-<span class="gp">$ </span>ln<span class="w"> </span>-s<span class="w"> </span>/mnt/rstudio_host<span class="w"> </span>lib
+<div class="highlight"><pre><span></span><code>ln<span class="w"> </span>-s<span class="w"> </span>/safe_data/
+ln<span class="w"> </span>-s<span class="w"> </span>/safe_outputs/
+ln<span class="w"> </span>-s<span class="w"> </span>/scratch/
+ln<span class="w"> </span>-s<span class="w"> </span>/mnt/rstudio_host<span class="w"> </span>lib
 </code></pre></div>
 </div>
 <hr />
 <h2 id="installing-r-packages">Installing R packages</h2>
 <p>RStudio Server is configured with your web proxy environment variables so you can install packages from CRAN when using RStudio Server. It is recommended that you install R packages into <code>/mnt/rstudio_host</code> so that you can reuse these the next time you run the app on the same back-end.</p>
+<p>There are a number of ways you can use such a directory within RStudio Server. One examples is as follows. R and RStudio Server resources online may suggest others.</p>
+<h3 id="install-packages-within-mntrstudio_host">Install packages within <code>/mnt/rstudio_host</code></h3>
+<p>Install packages within <code>/mnt/rstudio_host</code>. For example:</p>
+<div class="highlight"><pre><span></span><code><span class="o">&gt;</span><span class="w"> </span><span class="nf">install.packages</span><span class="p">(</span><span class="s">&#39;PACKAGE_NAME&#39;</span><span class="p">,</span><span class="w"> </span><span class="n">lib</span><span class="o">=</span><span class="s">&#39;/mnt/rstudio_host/&#39;</span><span class="p">)</span>
+</code></pre></div>
+<p>Any R code that needs the packages needs to include the path to the directory. For example:</p>
+<div class="highlight"><pre><span></span><code><span class="o">&gt;</span><span class="w"> </span><span class="nf">.libPaths</span><span class="p">(</span><span class="s">&#39;/mnt/rstudio_host&#39;</span><span class="p">)</span>
+<span class="o">&gt;</span><span class="w"> </span><span class="nf">find.package</span><span class="p">(</span><span class="s">&#39;PACKAGE_NAME&#39;</span><span class="p">)</span>
+<span class="p">[</span><span class="m">1</span><span class="p">]</span><span class="w"> </span><span class="s">&quot;/mnt/rstudio_host/PACKAGE_NAME&quot;</span>
+<span class="o">&gt;</span><span class="w"> </span><span class="nf">library</span><span class="p">(</span><span class="n">PACKAGE_NAME</span><span class="p">)</span>
+</code></pre></div>
+<p>Any packages will be visible on the back-end upon which the app runs. For example:</p>
+<div class="highlight"><pre><span></span><code>$<span class="w"> </span>ls<span class="w"> </span><span class="nv">$HOME</span>/.local/share/ondemand/apps/rstudio_app/
+PACKAGE_NAME
+</code></pre></div>
 <hr />
 <h2 id="view-job-files">View job files</h2>
 <p>On a job's job card, click the <strong>Session ID</strong> link to open the <a href="../../files/">File Manager</a>, pointing at the job context directory for the job on the Open OnDemand VM.</p>