Comment on page
Analyses
exbuilder comes with two analysis containers (
jupyter and rstudio) so you can choose your preferred analysis environment. You can remove the container you do not need if you wish to.The
jupyter container is built from the exbuilder/jupyter image, an extension of the jupyter/datascience-notebook which contains kernels for Python, R, and Julia. To analyze with Jupyter, start the jupyter container withdocker-compose up -d --build jupyter
Then visit https://localhost:8989 and enter the token
password. Files and folders you create in the work folder in Jupyter will save in the analyses folder of your exbuilder project on your local machine.The
rstudio container is built from the exbuilder/rstudio image, an extension of the rocker/verse image. To analyze with RStudio, start the rstudio container with:docker-compose up -d --build rstudio
Then visit https://localhost:8787 and enter the token
password. Files and folders you create in the work folder in rstudio will save the analyses folder of your exbuilder project on your local machine.To build the container from a different image, edit the
docker-compose.yml file in your exbuilder project. Under the jupyter or rstudio services, change the image line to the image you'd like to use.# exbuilder's default image
jupyter:
image: "exbuilder/jupyter:4.0.3"
# change to the jupyter datascience notebook container
jupyter:
image: "jupyter/datascience-notebook:4.0.3"
Many pre-built images are available on Docker Hub. For Jupyter, we suggest the jupyter/datascience-notebook containers. For RStudio, we suggest the rocker/tidyverse or rocker/verse containers.
If you choose to use a custom image, please keep in mind that exbuilder's
jupyter and rstudio images include drivers for connecting to exbuilder's postgres database that your custom image might be missing. These drivers can be added by extending the container image you select by adding the following to your Dockerfile :FROM whateverbase/image
# as the root user
USER root
# get postgres prereqs
RUN apt-get update && \
apt-get install -y libpq-dev && \
apt-get clean && rm -rf /var/lib/apt/lists/*
Note that
docker-compose.yml and Dockerfile are two different things! Read the extend the container image section to learn how to use a Dockerfile with exbuilder. To extend an existing image, you'll need to do two things: (1) add a
Dockerfile to your exbuilder project and (2) tell the jupyter or rstudio service to build the container from this Dockerfile. Here we will illustrate adding an R package to exbuider's analysis container (rstudio or jupyter).To add an R package to exbuilder's
jupyter container, create a Dockerfile like this# start with the existing container
FROM exbuilder/jupyter:4.0.3
# list who maintains the container (you)
LABEL maintainer="Your Name <[email protected]>"
# if there is no conda version of the package, as the root user
USER root
# install via R
RUN R -e "install.packages('packagename', repos='http://cran.rstudio.com/')"
# then as the notebook user
USER $NB_UID
# install any conda versions of the package (this way is preferred)
RUN conda install --quiet --yes \
'r-packagename' $$ \
conda clean --all -f -y && \
fix-permissions "${CONDA_DIR}" && \
fix-permissions "/home/${NB_USER}"
To add an R package to exbuilder's
rstudio container, create a Dockerfile like this#start with the existing container
FROM exbuilder/rstudio:4.0.3
# list who maintains the container (you)
LABEL maintainer="Your Name <[email protected]>"
# as the root user
USER root
# change repo to cran
RUN echo "options(repos = c(CRAN = 'https://cran.rstudio.com/'), download.file.method = 'libcurl')" >> /usr/local/lib/R/etc/Rprofile.site
# install more packages
RUN install2.r --error \
package1 \
package2
Rather than using an existing image, you'll now tell docker to build the image from your new
Dockerfile. Open your docker-compose.yml file and make the following changes.# before we create the container from an image
rstudio:
image: "exbuilder/rstudio:4.0.3"
# change to build the container from the dockerfile
rstudio:
build:
context: . #make the context this directory with .
dockerfile: Dockerfile # specify path to dockerfile
Above we extended the image inside the project with a Dockerfile, but you could instead build your own custom image and push it to Docker Hub. Some researchers might like to create a Docker Hub for themselves or their lab groups, kind of like a library of machines that your lab has used.
To do this, you first you'll need to login to Docker Hub (create an account if you don't have one already) and create a repository there. Then, from your command line, login like this:
docker login --username=dockerhubusername [email protected]
To build your container, run the following command, where context is the path to the folder containing your
Dockerfile. For exbuilder, we hold the Dockerfiles for every containers in a single GitHub repository and push each container we build (e.g. jupyter, rstudio, etc) to its own Docker Hub repository. docker build -t dockerhubusername/dockerhubrepo context
Test your image locally to make sure everything is working. For example, when testing a customized
rstudio image, you'll likely want to pass an environment variable (password) and the port (8787), like this.docker run -d -e PASSWORD=password -p 8787:8787 dockerhubusername/dockerhubrepo
Then use the following command to retrieve the id of your newly built image
docker images
And tag your new image with something useful, using the id you grabbed in the last step. We usually use the R (or python or julia) version to make it easy for users to select the container they need.
docker tag 36a7fd4396e dockerhubusername/dockerhubrepo:4.0.3
Finally, push your tagged image to Docker Hub
docker push dockerhubusername/dockerhubrepo:4.0.3
Then you (and anyone else if you make your images public) can pull this image with
docker pull dockerhubusername/dockerhubrepo:4.0.3
Or use it in a
docker-compose.yml filerstudio:
images: dockerhubusername/dockerhubrepo:4.0.3
Last modified 2yr ago