Merge pull request #145 from nmfs-opensci/dev

update info with the scripts

book/configuration_files.qmd

@@ -1,10 +1,15 @@
 # Configuration files
 
-The presence of these files will trigger the following behavior. Do not use these names if you do not want this behavior and you instead want
-to write you own code in your Docker file.
-
 ## environment.yml
 
+The `install-conda-packages.sh` script will install conda packages to the conda notebook environment, the user environment in the py-rocket-base image (same as for pangeo and repo2docker images). 
+
+Here is the code for your Docker file. You can name the conda package file to something other than `environment.yml`. Make sure your file has `name:`. The name is arbitrary. It is ignored but required for the script.
+
+```
+RUN /pyrocket_scripts/install-conda-packages.sh environment.yml
+```
+
 This is a standard format. You can add version pinning.
 
 environment.yml
@@ -17,8 +22,40 @@ dependencies:
   - numpy
 ```
 
+## conda-lock.yml
+
+Instead of a list of conda packages (typically called environment.yml), you can use a conda lock file instead.
+
+Here is the code for your Docker file. You can name your conda lock file something other than `conda-lock.yml`.
+```
+RUN /pyrocket_scripts/install-conda-packages.sh conda-lock.yml
+```
+
+## requirments.txt
+
+The `install-pip-packages.sh` script will install packages using `pip`.  Here is the code for your Docker file. You can name your pip package file something other than `requirements.txt`.
+
+```
+RUN /pyrocket_scripts/install-pip-packages.sh requirements.txt
+```
+
+requirements.txt
+```
+#a package
+harmony-py
+
+```
+
 ## install.R
 
+The `install-r-packages.sh` script will run the supplied R script which you can use to install R packages to the system library. 
+
+Here is the code for your Docker file. You can name the R script file to something other than `install.R`. Make sure your file is an R script.
+
+```
+RUN /pyrocket_scripts/install-r-packages.sh install.R
+```
+
 install.R example
 ```
 # to match rocker/verse:4.4 used in py-rocker-base
@@ -30,20 +67,29 @@ install.packages(list.of.packages, repos=repo)
 
 ### Add R geospatial packages
 
-Geospatial packages require some linux packages. To get this working in your docker image add this to your Docker file:
+Geospatial packages require some linux packages. To get this working in your Docker image add this to your Docker file:
 
+Dockerfile
 ```
 FROM ghcr.io/nmfs-opensci/py-rocket-base:latest
 
 USER root
-RUN /rocker_scripts/install_geospatial.sh
-USER ${NB_USER} 
+RUN PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && \
+    /rocker_scripts/install_geospatial.sh
+USER ${NB_USER}
 ```
 
 ## apt.txt
 
-Standard format. You can have comments.
+The `install-apt-packages.sh` script will install packages with `apt-get`. Here is the code for your Docker file. You can name the apt file of packages names to something other than `apt.txt`. Comments and newlines are allowed. Installation requires root.
 
+```
+USER root
+RUN /pyrocket_scripts/install-apt-packages.sh apt.txt
+USER ${NB_USER}
+```
+
+apt.txt example
 ```
 # Some useful stuff
 tk-dev
@@ -54,7 +100,11 @@ cmocean
 
 ## postBuild
 
-This is a script that will be run after all the other commands. This script is run as jovyan not as root. If you need commands run as root, you will need to add these to the Docker file.
+The `run-postbuild.sh` script can be run as root or jovyan (`${NB_USER}`). This script does not accept a file name. You need to name your postBuild script `postBuild` and put at the base level with your Docker file.
+
+```
+RUN /pyrocket_scripts/run-postbuild.sh
+```
 
 postBuild
 ```
@@ -66,10 +116,13 @@ set -e
 
 ## start
 
-`start` bash code is run when the image starts. py-rocker-base has a start script at `${REPO_DIR}/start` which loads the Desktop applications. If you change that start file, then the Desktop apps will not be loaded properly. 
+The `start` bash code is run when the image starts. py-rocker-base has a start script at `${REPO_DIR}/start` which loads the Desktop applications. If you change that start file (by copying your start file onto that location), then the Desktop apps will not be loaded properly. Instead, the `setup-start.sh` will add your start file to the end of `${REPO_DIR}/start` so that the Desktop is still setup properly.
 
-By default, if you include `start` in the child repo then that script is sourced within the `${REPO_DIR}/start` script at the end. If you don't want that behavior and want the whole start script replaced, then you will need to do that in your Docker file by copying your start file onto `${REPO_DIR}/start`.
+The `setup-start.sh` script does not accept a file name. You need to name your start script `start` and put at the base level with your Docker file.
 
+```
+RUN /pyrocket_scripts/setup-start.sh
+```
 
 ## Desktop applications
 

book/customizing.qmd

@@ -1,26 +1,33 @@
 # Using py-rocket-base
 
-py-rocket-base is designed to be used in the FROM line of a Dockerfile. It behaves like repo2docker in that it looks for special files and will 
-install Python packages or R packages if those special files are present. You do not need to add anything to the Dockerfile to have it process these files. py-rocker-base does this automatically for you (via ONBUILD commands).
+py-rocket-base is designed to be used in the FROM line of a Dockerfile similar to rocker images. It includes directories called `\pyrocket_scripts` and `\rocker_scripts` that will help you do common tasks for scientific docker images. You do not have to use these scripts. If you are familiar with writing Docker files, you can write your own code. The exception is installation of Desktop files. Properly adding Desktop applications to py-rocket-base requires the use of the `\pyrocket_scripts/install-desktop.sh` script. The start file is also an exception. See the discussion in the configuration files.
 
-If you don't want it to do this then do not name your files one of these names:
+**Calling the scripts**
 
-- environment.yml
-- install.R
-- postBuild
-- apt.txt
-- start
+The format for calling the pyrocket and rocker scripts is the following.
+```
+RUN /pyrocket_scripts/install-conda-packages.sh environment.yml
+```
+
+Note that PATH must be given for the subshell since rocker installation scripts will fail with conda on the path.
+```
+USER root
+RUN PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && \
+    /rocker_scripts/install_geospatial.sh
+USER ${NB_USER}
+```
 
 ## File structure
 
-Only Dockerfile is required. The rest are optional. 
+Here is a typical repo structure. Only the Dockerfile is required. The rest are optional. The files names, `apt.txt`, `environment.yml`, `requirements.txt` and `install.R` are optional. You can name these files other names and still use them in the pyrocket scripts. `Desktop`, `start` and `postBuild` must be named exactly this to use them in the pyrocket scripts (these scripts do not take filename arguments).
 
 ```
 your-repo/
 ├── Dockerfile
 ├── apt.txt
 ├── environment.yml
 ├── install.R
+├── requirements.txt
 ├── postBuild
 ├── start
 ├── Desktop/
@@ -29,7 +36,7 @@ your-repo/
 │   └── qgis.png
 ```
 
-Read [configuration_files](configuration_files.html) to learn about apt.txt, environment.yml, install.R, postBuild, and start. Read [Desktop](desktop.html) to learn about the Desktop folder and files for applications.
+Read [configuration_files](configuration_files.html) to learn about apt.txt, environment.yml, install.R, requirements.txt, postBuild, and start. Read [Desktop](desktop.html) to learn about the Desktop folder and files for applications.
 
 ## Examples
 
@@ -46,6 +53,8 @@ your-repo/
 Dockerfile
 ```
 FROM ghcr.io/nmfs-opensci/py-rocket-base:latest
+
+RUN /pyrocket_scripts/install-conda-packages.sh environment.yml
 ```
 
 environment.yml
@@ -71,6 +80,8 @@ your-repo/
 Dockerfile
 ```
 FROM ghcr.io/nmfs-opensci/py-rocket-base:latest
+
+RUN /pyrocket_scripts/install-r-packages.sh install.R
 ```
 
 install.R
@@ -82,6 +93,34 @@ list.of.packages <- c("ncdf4", "httr", "plyr", "lubridate")
 install.packages(list.of.packages, repos=repo)
 ```
 
+### Add some linux packages
+
+You want to add some linux packages with apt-get. `apt-get` requires root so you will need to switch to root and switch back to `${NB_USER}`.
+
+```
+your-repo/
+├── Dockerfile
+├── apt.txt
+```
+
+Dockerfile
+```
+FROM ghcr.io/nmfs-opensci/py-rocket-base:latest
+
+USER root
+RUN /pyrocket_scripts/install-apt-packages.sh apt.txt
+USER ${NB_USER}
+```
+
+apt.txt
+```
+# a package
+libgl1-mesa-glx
+
+# Another
+vim
+```
+
 ### Add R geospatial packages
 
 Geospatial packages require some linux packages. To get this working in your Docker image add this to your Docker file:
@@ -91,8 +130,9 @@ Dockerfile
 FROM ghcr.io/nmfs-opensci/py-rocket-base:latest
 
 USER root
-RUN /rocker_scripts/install_geospatial.sh
-USER ${NB_USER} 
+RUN PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && \
+    /rocker_scripts/install_geospatial.sh
+USER ${NB_USER}
 ```
 
 You have access to all the rocker_scripts and you can run these similar to the line above.

book/desktop.qmd

@@ -8,6 +8,14 @@ py-rocket-base puts these `.desktop` files in `/usr/share/Desktop`. Typically th
 
 ## Adding an application in your child docker image
 
+Use the pyrocket script, `install-desktop.sh` to set up the desktop and move your files to the proper location. Here is the code for your Docker file. This script must be run as root. It does not take any arguments. Instead you include your desktop files in a directory called `Desktop` at the base level with your Docker file.
+
+```
+USER root
+RUN /pyrocket_scripts/install-desktop.sh
+USER ${NB_USER}
+```
+
 ### Create the Desktop directory
 
 Create the directory and add the .desktop and optional .png and .xml files. py-rocket-base will move them to the correct places (`/usr/share/applications` and `/usr/share/Desktop`, `/usr/share/mime/packages` and icon locations).