Merge pull request #163 from kaczmarj/examples

FIX+ENH: pip install and examples

.gitignore

@@ -14,3 +14,6 @@ coverage.xml
 *.pyc
 *.tar
 *.tar.gz
+
+/build
+/dist

README.md

@@ -1,6 +1,8 @@
 # Neurodocker
 
 [![build status](https://img.shields.io/circleci/project/github/kaczmarj/neurodocker/master.svg)](https://circleci.com/gh/kaczmarj/neurodocker/tree/master)
+[![build status](https://img.shields.io/docker/pulls/kaczmarj/neurodocker.svg)](https://hub.docker.com/r/kaczmarj/neurodocker/)
+[![build status](https://img.shields.io/pypi/pyversions/neurodocker.svg)](https://pypi.org/project/neurodocker/)
 
 _Neurodocker_ is a command-line program that generates custom Dockerfiles and Singularity recipes for neuroimaging and minifies existing containers.
 
@@ -15,10 +17,23 @@ Examples:
 
 # Installation
 
-Use the _Neurodocker_ Docker image:
+Use the _Neurodocker_ Docker image (recommended):
 
+```shell
+$ docker run --rm kaczmarj/neurodocker:0.4.0rc1 --help
+```
+
+This project can also be installed with `pip`:
+
+```shell
+$ pip install neurodocker
+$ neurodocker --help
 ```
-docker run --rm kaczmarj/neurodocker:0.4.0 --help
+
+If the `pip install` command above gives a permissions error, install as a non-root user:
+
+```shell
+$ pip install --user neurodocker
 ```
 
 Note: it is not yet possible to minimize Docker containers using the _Neurodocker_ Docker image.
@@ -97,11 +112,11 @@ The canonical examples install ANTs version 2.2.0 on Ubuntu 18.04.
 ### Docker
 
 ```shell
-$ docker run --rm kaczmarj/neurodocker:0.4.0 generate docker \
+$ docker run --rm kaczmarj/neurodocker:0.4.0rc1 generate docker \
     --base ubuntu:18.04 --pkg-manager apt --ants version=2.2.0
 
 # Build image by piping Dockerfile to `docker build`
-$ docker run --rm kaczmarj/neurodocker:0.4.0 generate docker \
+$ docker run --rm kaczmarj/neurodocker:0.4.0rc1 generate docker \
     --base ubuntu:18.04 --pkg-manager apt --ants version=2.2.0 | docker build -
 ```
 
@@ -110,19 +125,14 @@ $ docker run --rm kaczmarj/neurodocker:0.4.0 generate docker \
 Install ANTs on Ubuntu 18.04.
 
 ```shell
-$ docker run --rm kaczmarj/neurodocker:0.4.0 generate singularity \
+$ docker run --rm kaczmarj/neurodocker:0.4.0rc1 generate singularity \
     --base ubuntu:18.04 --pkg-manager apt --ants version=2.2.0
 ```
 
 
 ## Minimize existing Docker image
 
-The _Neurodocker_ Python package will have to be installed for container minimization:
-
-```shell
-pip install --no-cache-dir https://github.com/kaczmarj/neurodocker/tarball/master
-```
-
+_Neurodocker_ must be `pip` installed for container minimization.
 
 In the following example, a Docker image is built with ANTs version 2.2.0 and a functional scan. The image is minified for running `antsMotionCorr`. The original ANTs Docker image is 1.85 GB, and the "minified" image is 365 MB.
 

examples/conda_python/Dockerfile

@@ -1,91 +1,91 @@
-# Generated by Neurodocker v0.3.1-19-g8d02eb4.
+# Generated by Neurodocker version 0.3.2-188-g86e7b9e
+# Timestamp: 2018-04-27 13:29:28 UTC
 #
 # Thank you for using Neurodocker. If you discover any issues
 # or ways to improve this software, please submit an issue or
 # pull request on our GitHub repository:
-#     https://github.com/kaczmarj/neurodocker
 #
-# Timestamp: 2017-11-07 03:03:23
+#     https://github.com/kaczmarj/neurodocker
 
 FROM neurodebian:stretch-non-free
 
-ARG DEBIAN_FRONTEND=noninteractive
+ARG DEBIAN_FRONTEND="noninteractive"
 
-#----------------------------------------------------------
-# Install common dependencies and create default entrypoint
-#----------------------------------------------------------
 ENV LANG="en_US.UTF-8" \
-    LC_ALL="C.UTF-8" \
+    LC_ALL="en_US.UTF-8" \
     ND_ENTRYPOINT="/neurodocker/startup.sh"
-RUN apt-get update -qq && apt-get install -yq --no-install-recommends  \
-    	apt-utils bzip2 ca-certificates curl locales unzip \
+RUN export ND_ENTRYPOINT="/neurodocker/startup.sh" \
+    && apt-get update -qq \
+    && apt-get install -y -q --no-install-recommends \
+           apt-utils \
+           bzip2 \
+           ca-certificates \
+           curl \
+           locales \
+           unzip \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* \
-    && localedef --force --inputfile=en_US --charmap=UTF-8 C.UTF-8 \
+    && sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen \
+    && dpkg-reconfigure --frontend=noninteractive locales \
+    && update-locale LANG="en_US.UTF-8" \
     && chmod 777 /opt && chmod a+s /opt \
     && mkdir -p /neurodocker \
     && if [ ! -f "$ND_ENTRYPOINT" ]; then \
-         echo '#!/usr/bin/env bash' >> $ND_ENTRYPOINT \
-         && echo 'set +x' >> $ND_ENTRYPOINT \
-         && echo 'if [ -z "$*" ]; then /usr/bin/env bash; else $*; fi' >> $ND_ENTRYPOINT; \
-       fi \
+         echo '#!/usr/bin/env bash' >> "$ND_ENTRYPOINT" \
+    &&   echo 'set -e' >> "$ND_ENTRYPOINT" \
+    &&   echo 'if [ -n "$1" ]; then "$@"; else /usr/bin/env bash; fi' >> "$ND_ENTRYPOINT"; \
+    fi \
     && chmod -R 777 /neurodocker && chmod a+s /neurodocker
+
 ENTRYPOINT ["/neurodocker/startup.sh"]
 
 RUN apt-get update -qq \
-    && apt-get install -y -q --no-install-recommends vim \
-                                                     emacs-nox \
+    && apt-get install -y -q --no-install-recommends \
+           vim \
+           emacs-nox \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
-# Create new user: neuro
 RUN useradd --no-user-group --create-home --shell /bin/bash neuro
 USER neuro
 
-#------------------
-# Install Miniconda
-#------------------
-ENV CONDA_DIR=/opt/conda \
-    PATH=/opt/conda/bin:$PATH
-RUN echo "Downloading Miniconda installer ..." \
-    && miniconda_installer=/tmp/miniconda.sh \
-    && curl -sSL -o $miniconda_installer https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh \
-    && /bin/bash $miniconda_installer -b -p $CONDA_DIR \
-    && rm -f $miniconda_installer \
+ENV CONDA_DIR="/opt/miniconda-latest" \
+    PATH="/opt/miniconda-latest/bin:$PATH"
+RUN export PATH="/opt/miniconda-latest/bin:$PATH" \
+    && echo "Downloading Miniconda installer ..." \
+    && conda_installer="/tmp/miniconda.sh" \
+    && curl -fsSL --retry 5 -o "$conda_installer" https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh \
+    && bash "$conda_installer" -b -p /opt/miniconda-latest \
+    && rm -f "$conda_installer" \
+    && conda update -yq -nbase conda \
     && conda config --system --prepend channels conda-forge \
     && conda config --system --set auto_update_conda false \
     && conda config --system --set show_channel_urls true \
-    && conda clean -tipsy && sync
-
-#-------------------------
-# Create conda environment
-#-------------------------
-RUN conda create -y -q --name neuro_py36 python=3.6 \
-                                         jupyter \
-                                         jupyterlab \
-                                         jupyter_contrib_nbextensions \
-                                         matplotlib \
-                                         scikit-learn \
-                                         seaborn \
     && sync && conda clean -tipsy && sync \
-    && /bin/bash -c "source activate neuro_py36 \
-      && pip install -q --no-cache-dir nilearn" \
+    && conda create -y -q --name neuro_py36 \
+    && conda install -y -q --name neuro_py36 \
+           python=3.6 \
+           jupyter \
+           jupyterlab \
+           jupyter_contrib_nbextensions \
+           matplotlib \
+           scikit-learn \
+           seaborn \
+    && sync && conda clean -tipsy && sync \
+    && bash -c "source activate neuro_py36 \
+    &&   pip install -q --no-cache-dir \
+             nilearn" \
     && sync \
     && sed -i '$isource activate neuro_py36' $ND_ENTRYPOINT
 
-# User-defined instruction
 RUN mkdir -p ~/.jupyter && echo c.NotebookApp.ip = \"0.0.0.0\" > ~/.jupyter/jupyter_notebook_config.py
 
 WORKDIR /home/neuro
 
 CMD ["jupyter-notebook"]
 
-#--------------------------------------
-# Save container specifications to JSON
-#--------------------------------------
 RUN echo '{ \
     \n  "pkg_manager": "apt", \
-    \n  "check_urls": false, \
     \n  "instructions": [ \
     \n    [ \
     \n      "base", \
@@ -105,10 +105,20 @@ RUN echo '{ \
     \n    [ \
     \n      "miniconda", \
     \n      { \
-    \n        "conda_install": "python=3.6 jupyter jupyterlab jupyter_contrib_nbextensions matplotlib scikit-learn seaborn", \
-    \n        "pip_install": "nilearn", \
+    \n        "conda_install": [ \
+    \n          "python=3.6", \
+    \n          "jupyter", \
+    \n          "jupyterlab", \
+    \n          "jupyter_contrib_nbextensions", \
+    \n          "matplotlib", \
+    \n          "scikit-learn", \
+    \n          "seaborn" \
+    \n        ], \
+    \n        "pip_install": [ \
+    \n          "nilearn" \
+    \n        ], \
     \n        "env_name": "neuro_py36", \
-    \n        "activate": "True" \
+    \n        "activate": true \
     \n      } \
     \n    ], \
     \n    [ \
@@ -125,7 +135,5 @@ RUN echo '{ \
     \n        "jupyter-notebook" \
     \n      ] \
     \n    ] \
-    \n  ], \
-    \n  "generation_timestamp": "2017-11-07 03:03:23", \
-    \n  "neurodocker_version": "0.3.1-19-g8d02eb4" \
+    \n  ] \
     \n}' > /neurodocker/neurodocker_specs.json

examples/conda_python/README.md

@@ -1,20 +1,41 @@
-In this directory you can find a `Dockerfile` with conda python environment.
+# conda python example
 
-The bash script `create_dockerfile.sh` contains a `neurodocker` command that was used to create the `Dockerfile`.
+In this directory you can find a `Dockerfile` and `Singularity` file with a conda python environment.
 
-The `Dockerfile` contains:
+The shell script `generate.sh` contains a `neurodocker` command that creates the `Dockerfile` and `Singularity` file.
 
- - using `neurodebian:stretch-non-free` as a base image
- - installing text editors
- - creating a conda environment and installing various python library including jupyter-notebook; most of the libraries are installed using `conda`, and `nilearn` is installed using a `pip` command; the environment will be automatically activated
- - changing a jupyter configuartion, so you'll be able to open notebooks locally
- - using `jupyter-notebook` as a default command
+Both specs:
 
+ - use `neurodebian:stretch-non-free` as the base image
+ - install text editors
+ - create a conda environment and installing various python library including jupyter-notebook; most of the libraries are installed using `conda`, and `nilearn` is installed using a `pip` command; the environment will be automatically activated
+ - change the jupyter configuration, so you'll be able to open notebooks locally
 
-You can test the script and `Dockerfile`
+The Dockerfile uses `jupyter-notebook` as the default command. The Singularity file will start a bash shell by default.
 
- - creating a `Dockerfile`: `bash create_dockerfile.sh`
- - building a Docker image (this will take a few minutes): `docker build -t test/conda .`
- - running a Docker container: `docker run -it --rm -p8888:8888 test/conda` (container should start `jupyter-notebook`, you can copy the link and paste to your browser)
- - you can still start container with `bash` instead of `jupyter-notebook`: `docker run -it --rm test/conda bash`
-
+
+## Docker
+
+```shell
+# Generate Dockerfile
+$ ./generate.sh
+# Build Docker image
+$ docker build -t test/conda .
+# Run the container (start jupyter notebook)
+$ docker run --rm -it -p 8888:8888 test/conda
+# Start interactive bash shell
+$ docker run --rm -it test/conda bash
+```
+
+## Singularity
+
+```shell
+# Generate Singularity file
+$ ./generate.sh
+# Build Singularity image
+$ singularity build jupyter.sqsh Singularity
+# Run the container (start jupyter notebook)
+$ singularity run jupyter.sqsh jupyter-notebook
+# Start interactive bash shell
+$ singularity run jupyter.sqsh
+```