1 Using py-rocket-base

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.

1.1 helper scripts

1.1.1 pyrocket scripts

How to use the helper scripts is shown in configuration files. The helper scripts provide code to do common tasks. Users can write their own Docker file code to do these tasks but the helper scripts provide standardized code. The scripts are

install-conda-packages.sh
install-pip-packages.sh
install-r-packages.sh
install-apt-packages.sh
install-vscode-extensions.sh
install-desktop.sh
setup-start.sh
run-postbuild.sh

1.1.2 rocker scripts

The rocker docker stack also includes a set of scripts for extending rocker packages. These are included py-rocket-base.

1.1.3 Calling the scripts

The format for calling the pyrocket and rocker scripts is the following.

pyrocket scripts take files (or a path to a directory with Desktop files) as arguments. The COPY command is needed to copy the file into the Docker build context where it can be used in RUN commands. Without this you will get a “file not found” error. Removing the file after you are done with it will clean up your image files.

COPY environment.yml environment.yml
RUN /pyrocket_scripts/install-conda-packages.sh environment.yml && \
  rm environment.yml

Rocker scripts do not take arguments. Note that PATH must be given since rocker installation scripts will fail with conda on the path. The path specification will apply only within the specific RUN context and must be in the same RUN that the rocker script is run. The scripts should be run as root.

USER root
RUN PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && \
    /rocker_scripts/install_geospatial.sh
USER ${NB_USER}

1.2 Repository file structure

Here is a typical repo structure. Only the Dockerfile is required. The rest are optional. The exact files names, apt.txt, environment.yml, requirements.txt, install.R, etc are optional, meaning you can name these files whatever you want. The pyrocket scripts take filename or directory arguments.

your-repo/
├── Dockerfile
├── apt.txt
├── environment.yml
├── install.R
├── requirements.txt
├── postBuild
├── start
├── Desktop/
│   ├── qgis.desktop
│   ├── qgis.xml
│   └── qgis.png

Read configuration_files to learn about the files. Read Desktop to learn about the Desktop folder and files for applications.

1.3 Examples

1.3.1 Add some Python packages

You want to add some Python packages to the conda notebook environment.

your-repo/
├── Dockerfile
├── environment.yml

Dockerfile

FROM ghcr.io/nmfs-opensci/py-rocket-base:latest

COPY environment.yml environment.yml
RUN /pyrocket_scripts/install-conda-packages.sh environment.yml && \
  rm environment.yml

environment.yml

name: required
channels:
  - conda-forge
dependencies:
  - cmocean
  - numpy

1.3.2 Add R packages

Add an R script to install packages. Important: packages that have linux dependencies (e.g. all the spatial packages depend on GDAL) will not work if you use install.packages(). GDAL will not be installed.

your-repo/
├── Dockerfile
├── install.R

Dockerfile

FROM ghcr.io/nmfs-opensci/py-rocket-base:latest

COPY install.R install.R
RUN /pyrocket_scripts/install-r-packages.sh install.R && rm install.R

install.R

# to match rocker/verse:4.4 used in py-rocker-base
# look up the date that the Rocker image was created and put that
repo <- "https://p3m.dev/cran/__linux__/jammy/2024-05-13"
list.of.packages <- c("ncdf4", "httr", "plyr", "lubridate")
install.packages(list.of.packages, repos=repo)

1.3.3 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
COPY apt.txt apt.txt
RUN /pyrocket_scripts/install-apt-packages.sh apt.txt && rm apt.txt
USER ${NB_USER}

apt.txt

# a package
libgl1-mesa-glx

# Another
vim

1.3.4 Add R geospatial packages

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 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.