add info on the R kernel

Author: eeholmes

README.md

@@ -37,3 +37,11 @@ py-rocket-base has pyrocket and rocket scripts that you can use to help customiz
 The original [py-rocket 1.0](https://github.com/NASA-Openscapes/py-rocket) was developed by Luis Lopez and was built off a Rocker base image. Carl Boettiger and Eli Holmes later altered the image (py-rocket 2.0) so that the Python environment matched the Pangeo image structure but the image was still built off a Rocker image. Subsequently, Carl Boettiger developed [repo2docker-r](https://github.com/boettiger-lab/repo2docker-r) that creates a JupyterHub-compatible image that uses a [Jupyter docker stack image](https://jupyter-docker-stacks.readthedocs.io/en/latest/) as base. For py-rocker 3.0, Eli Holmes used Carl's ideas but used [repo2docker](https://repo2docker.readthedocs.io/en/latest/) and [repo2docker-action](https://github.com/jupyterhub/repo2docker-action) to build the base image. To do this, the [CryoCloud hub image](https://github.com/CryoInTheCloud/hub-image) repo was used for the basic structure and approach. Eli added the `rocker.sh` script and `appendix` modifications to install R and RStudio via the Rocker scripts (rather than using a Rocker image as base). Yuvi Panda (repo2docker) gave input throughout the process as snags were hit.
 
 **Why Rocker for the R/RStudio environment?** The Rocker images are the standard for R/RStudio contanier images. They are heavily tested and regularly updated. There is a large developer community that fixes problems and bugs. The stack has gone through major revisions to improve modularity and they constantly innovating (integration for machine-learning, CUDA, BLAS, spatial, etc., etc.). py-rocket is building off that work without using the images directly. Instead it uses the Docker file code and the installation scripts.  There are many other approaches to adding R and RStudio to images that work in JupyterHubs. See [repo2docker-r](https://github.com/boettiger-lab/repo2docker-r) that Carl developed and [r-conda](https://github.com/binder-examples/r-conda) for a conda native approach using repo2docker. py-rocket is not intended to create small images; it is intended to create images that emulate Rocker in the `/rstudio` environment on a JupyterHub.
+
+## Building the documentation
+
+```
+cd book
+quarto render .
+```
+This puts html in `docs`. Push to GitHub.

docs/developers.html

@@ -232,7 +232,7 @@ <h2 id="toc-title">Table of contents</h2>
   <ul class="collapse">
   <li><a href="#terminal-in-jupyter-lab" id="toc-terminal-in-jupyter-lab" class="nav-link" data-scroll-target="#terminal-in-jupyter-lab"><span class="header-section-number">8.9.1</span> Terminal in Jupyter Lab</a></li>
   </ul></li>
-  <li><a href="#notes-on-the-rstudio-environment" id="toc-notes-on-the-rstudio-environment" class="nav-link" data-scroll-target="#notes-on-the-rstudio-environment"><span class="header-section-number">8.10</span> Notes on the RStudio environment</a>
+  <li><a href="#notes-on-r-in-the-rstudio-or-jupyter-lab-environment" id="toc-notes-on-r-in-the-rstudio-or-jupyter-lab-environment" class="nav-link" data-scroll-target="#notes-on-r-in-the-rstudio-or-jupyter-lab-environment"><span class="header-section-number">8.10</span> Notes on R in the RStudio or Jupyter Lab environment</a>
   <ul class="collapse">
   <li><a href="#environmental-variables" id="toc-environmental-variables" class="nav-link" data-scroll-target="#environmental-variables"><span class="header-section-number">8.10.1</span> Environmental variables</a></li>
   <li><a href="#terminal-in-rstudio" id="toc-terminal-in-rstudio" class="nav-link" data-scroll-target="#terminal-in-rstudio"><span class="header-section-number">8.10.2</span> Terminal in RStudio</a></li>
@@ -655,20 +655,28 @@ <h3 data-number="8.9.1" class="anchored" data-anchor-id="terminal-in-jupyter-lab
 <p>For non-login bash shells (interactive), <code>/etc/bash.bashrc</code> determines the shell environment unless the user has created <code>~/.bashrc</code>, in which case that file determines the shell environment. In Jupyter Lab, you can start and interactive shell by running <code>bash</code> (from a terminal). Be aware that if you run <code>bash</code> it might look like the conda environment is deactivated but it is really not since the <code>PATH</code> still includes <code>conda</code> in it. If you are trying to get remove <code>conda</code> from the path (and get rid of all the conda environment variables) you need to run <code>conda deactivate</code> (2x).</p>
 </section>
 </section>
-<section id="notes-on-the-rstudio-environment" class="level2" data-number="8.10">
-<h2 data-number="8.10" class="anchored" data-anchor-id="notes-on-the-rstudio-environment"><span class="header-section-number">8.10</span> Notes on the RStudio environment</h2>
-<p><a href="https://github.com/jupyterhub/jupyter-rsession-proxy">jupyter-rsession-proxy</a> allows us to launch RStudio from Jupyter Lab, but the environment is different than the environment in Jupyter Lab.</p>
+<section id="notes-on-r-in-the-rstudio-or-jupyter-lab-environment" class="level2" data-number="8.10">
+<h2 data-number="8.10" class="anchored" data-anchor-id="notes-on-r-in-the-rstudio-or-jupyter-lab-environment"><span class="header-section-number">8.10</span> Notes on R in the RStudio or Jupyter Lab environment</h2>
+<p><a href="https://github.com/jupyterhub/jupyter-rsession-proxy">jupyter-rsession-proxy</a> in <code>environment.yml</code> allows us to launch RStudio from Jupyter Lab and <code>IRkernel</code> run in our R installation via this in the Docker file</p>
+<pre><code>RUN Rscript -e "install.packages('IRkernel')" &amp;&amp; \
+    PATH=/srv/conda/envs/notebook/bin:$PATH Rscript -e "IRkernel::installspec(name = 'ir', displayname = 'R ${R_VERSION}')"</code></pre>
+<p>creates a Jupyter Lab kernel called <code>R X.X.X</code> using our R installation (in <code>/usr/local/bin/R</code>) with all our libraries.</p>
+<p>However we enter the R environment (either in Jupyter Lab or RStudio), the environment is different than the default environment if you use the default Python environment (the conda ‘notebook’ environment).</p>
 <section id="environmental-variables" class="level3" data-number="8.10.1">
 <h3 data-number="8.10.1" class="anchored" data-anchor-id="environmental-variables"><span class="header-section-number">8.10.1</span> Environmental variables</h3>
 <ul>
-<li>PATH is different. conda is not on the path.</li>
-<li>None of the environmental variables in the docker file will be in the <code>/rstudio</code> environment. The start command affects <code>\lab</code> and <code>\notebook</code> but not <code>\rstudio</code>.</li>
+<li>PATH is different. conda is not on the path. Try <code>Sys.getenv("PATH")</code>. This is on purpose because the R geospatial packages get confused if one uses the GDAL associated with the conda environment. This is critical to know if you are using <code>reticulate</code> and <code>Python</code> inside of R. conda will not be on the path and all the Python libraries will not be accessible. If you want to use the conda environment, you have to run this. The first line tells R where the conda binary is because it has no way to find it since conda is not on its system PATH.</li>
 </ul>
-<p>If you need some environmental variable set, you will need to set those in <code>$R_HOME/etc/Rprofile.site</code> which is run when R starts.</p>
+<pre><code>options(reticulate.conda_binary = "/srv/conda/condabin/conda")
+reticulate::use_condaenv("/srv/conda/envs/notebook", required = TRUE)</code></pre>
+<ul>
+<li><strong>For RStudio only</strong>: None of the environmental variables in the docker file will be in the <code>/rstudio</code> environment. The start command affects <code>\lab</code> and <code>\notebook</code> but not <code>\rstudio</code>. I have made some attempt to add back in a few required ones in <code>/usr/local/lib/R/etc/Rprofile.site</code> but it is very minimal.</li>
+</ul>
+<p>If your users need some environmental variable set, they will need to set those in <code>$R_HOME/etc/Rprofile.site</code> which is run when R starts.</p>
 </section>
 <section id="terminal-in-rstudio" class="level3" data-number="8.10.2">
 <h3 data-number="8.10.2" class="anchored" data-anchor-id="terminal-in-rstudio"><span class="header-section-number">8.10.2</span> Terminal in RStudio</h3>
-<p>The default way that a terminal is started is <code>bash -l</code> which means it is a login terminal. When a login terminal launches, <code>/etc/profile</code> script is run. For this image, this script will execute all the scripts in the directory <code>/etc/profile.d</code>. You can add scripts there that you want to run when a login terminal is started. In particular, there is the script <code>init_conda.sh</code>. This ensures that when a terminal is opened from the Launcher in JupyterLab, the conda notebook environment is activated. However, we do not want this to happen in RStudio so the script checks if RSTUDIO==1 and R_HOME is set, if that is true then we are in the RStudio UI and conda should not be initialized.</p>
+<p>The default way that a terminal is started is <code>bash -l</code> which means it is a login terminal. When a login terminal launches, <code>/etc/profile</code> script is run. For this image, this script will execute all the scripts in the directory <code>/etc/profile.d</code>. You can add scripts there that you want to run when a login terminal is started. In particular, there is the script <code>init_conda.sh</code>. This ensures that when a terminal is opened from the Launcher in JupyterLab, the conda notebook environment is activated. However, we do not want this to happen in RStudio so the script checks if RSTUDIO==1 and R_HOME is set, if that is true then we are in the RStudio UI and conda should not be initialized (and is not).</p>
 
 
 </section>

docs/search.json

@@ -390,11 +390,11 @@
     ]
   },
   {
-    "objectID": "developers.html#notes-on-the-rstudio-environment",
-    "href": "developers.html#notes-on-the-rstudio-environment",
+    "objectID": "developers.html#notes-on-r-in-the-rstudio-or-jupyter-lab-environment",
+    "href": "developers.html#notes-on-r-in-the-rstudio-or-jupyter-lab-environment",
     "title": "8  Developer notes",
-    "section": "8.10 Notes on the RStudio environment",
-    "text": "8.10 Notes on the RStudio environment\njupyter-rsession-proxy allows us to launch RStudio from Jupyter Lab, but the environment is different than the environment in Jupyter Lab.\n\n8.10.1 Environmental variables\n\nPATH is different. conda is not on the path.\nNone of the environmental variables in the docker file will be in the /rstudio environment. The start command affects \\lab and \\notebook but not \\rstudio.\n\nIf you need some environmental variable set, you will need to set those in $R_HOME/etc/Rprofile.site which is run when R starts.\n\n\n8.10.2 Terminal in RStudio\nThe default way that a terminal is started is bash -l which means it is a login terminal. When a login terminal launches, /etc/profile script is run. For this image, this script will execute all the scripts in the directory /etc/profile.d. You can add scripts there that you want to run when a login terminal is started. In particular, there is the script init_conda.sh. This ensures that when a terminal is opened from the Launcher in JupyterLab, the conda notebook environment is activated. However, we do not want this to happen in RStudio so the script checks if RSTUDIO==1 and R_HOME is set, if that is true then we are in the RStudio UI and conda should not be initialized.",
+    "section": "8.10 Notes on R in the RStudio or Jupyter Lab environment",
+    "text": "8.10 Notes on R in the RStudio or Jupyter Lab environment\njupyter-rsession-proxy in environment.yml allows us to launch RStudio from Jupyter Lab and IRkernel run in our R installation via this in the Docker file\nRUN Rscript -e \"install.packages('IRkernel')\" && \\\n    PATH=/srv/conda/envs/notebook/bin:$PATH Rscript -e \"IRkernel::installspec(name = 'ir', displayname = 'R ${R_VERSION}')\"\ncreates a Jupyter Lab kernel called R X.X.X using our R installation (in /usr/local/bin/R) with all our libraries.\nHowever we enter the R environment (either in Jupyter Lab or RStudio), the environment is different than the default environment if you use the default Python environment (the conda ‘notebook’ environment).\n\n8.10.1 Environmental variables\n\nPATH is different. conda is not on the path. Try Sys.getenv(\"PATH\"). This is on purpose because the R geospatial packages get confused if one uses the GDAL associated with the conda environment. This is critical to know if you are using reticulate and Python inside of R. conda will not be on the path and all the Python libraries will not be accessible. If you want to use the conda environment, you have to run this. The first line tells R where the conda binary is because it has no way to find it since conda is not on its system PATH.\n\noptions(reticulate.conda_binary = \"/srv/conda/condabin/conda\")\nreticulate::use_condaenv(\"/srv/conda/envs/notebook\", required = TRUE)\n\nFor RStudio only: None of the environmental variables in the docker file will be in the /rstudio environment. The start command affects \\lab and \\notebook but not \\rstudio. I have made some attempt to add back in a few required ones in /usr/local/lib/R/etc/Rprofile.site but it is very minimal.\n\nIf your users need some environmental variable set, they will need to set those in $R_HOME/etc/Rprofile.site which is run when R starts.\n\n\n8.10.2 Terminal in RStudio\nThe default way that a terminal is started is bash -l which means it is a login terminal. When a login terminal launches, /etc/profile script is run. For this image, this script will execute all the scripts in the directory /etc/profile.d. You can add scripts there that you want to run when a login terminal is started. In particular, there is the script init_conda.sh. This ensures that when a terminal is opened from the Launcher in JupyterLab, the conda notebook environment is activated. However, we do not want this to happen in RStudio so the script checks if RSTUDIO==1 and R_HOME is set, if that is true then we are in the RStudio UI and conda should not be initialized (and is not).",
     "crumbs": [
       "<span class='chapter-number'>8</span>  <span class='chapter-title'>Developer notes</span>"
     ]

docs/sitemap.xml

@@ -34,7 +34,7 @@
   </url>
   <url>
     <loc>https://nmfs-opensci.github.io/py-rocket-base/developers.html</loc>
-    <lastmod>2025-03-04T18:45:41.534Z</lastmod>
+    <lastmod>2025-04-12T22:19:10.568Z</lastmod>
   </url>
   <url>
     <loc>https://nmfs-opensci.github.io/py-rocket-base/related.html</loc>