Merge pull request #231 from consideRatio/pr/update-custom-dockerfile-docs

Author: betatim

doc/tutorials/dockerfile.md

@@ -44,10 +44,8 @@ If you want to use a pre-existing Docker image, you may source it in your
 Dockerfile. For example, this code sources the Jupyter-Scipy notebook:
 
 ```Dockerfile
-
 # Note that there must be a tag
 FROM jupyter/scipy-notebook:cf6258237ff9
-
 ```
 
 See [Preparing your Dockerfile](preparing your dockerfile) for instructions on how to
@@ -86,9 +84,7 @@ For a Dockerfile to work on Binder, it must meet the following requirements:
    So in your dockerfile, you should have a command such as:
 
    ```Dockerfile
-
-   RUN pip install --no-cache-dir notebook==5.*
-
+   RUN pip install --no-cache-dir notebook
    ```
 
    If you would like to use the repository with an authenticated Binder you
@@ -101,13 +97,13 @@ For a Dockerfile to work on Binder, it must meet the following requirements:
 2. It must explicitly specify a tag in the image you source.
 
    When sourcing a pre-existing Docker image with `FROM`,
-**a tag is required**. The tag *cannot* be `latest`. Note that tag
+   **a tag is required**. The tag *cannot* be `latest`. Note that tag
    naming conventions differ between images, so we recommend using
    the SHA tag of the image.
 
    Here's an example of a Dockerfile `FROM` statement that would work.
 
-   ```
+   ```Dockerfile
    FROM jupyter/scipy-notebook:cf6258237ff9
    ```
 
@@ -119,16 +115,17 @@ For a Dockerfile to work on Binder, it must meet the following requirements:
 
    or
 
-   ```
+   ```Dockerfile
    FROM jupyter/scipy-notebook:latest
    ```
+
 3. It must set up a user whose uid is {}`1000`.
    It is bad practice to run processes in containers as root, and on binder
    we do not allow root container processes. If you are using an ubuntu or
    debian based container image, you can create a user easily with the following
    directives somewhere in your Dockerfile:
 
-   ```
+   ```Dockerfile
    ARG NB_USER=jovyan
    ARG NB_UID=1000
    ENV USER ${NB_USER}
@@ -144,14 +141,15 @@ For a Dockerfile to work on Binder, it must meet the following requirements:
    This is the user that will be running the jupyter notebook process
    when your repo is launched with binder. So any files you would like to
    be writeable by the launched binder notebook should be owned by this user.
+
 4. It must copy its contents to the `$HOME` directory and change permissions.
 
    To make sure that your repository contents are available to users,
    you must copy all contents to `$HOME` and then make this folder
    owned by the user you created in step 3. If you used the snippet provided
    in step 3, you can accomplish this copying with the following snippet:
 
-   ```
+   ```Dockerfile
    # Make sure the contents of our repo are in ${HOME}
    COPY . ${HOME}
    USER root
@@ -162,11 +160,12 @@ For a Dockerfile to work on Binder, it must meet the following requirements:
    This chown is required because Docker will be default
    set the owner to `root`, which would prevent users from editing files. Note that the repository
    should in general be clone with `COPY`; although `RUN git clone ...` is a valid command for the
-`Dockerfile`, it does not invalidate the build cache of mybinder. Thus, if available, the the cached
+   `Dockerfile`, it does not invalidate the build cache of mybinder. Thus, if available, the the cached
    repository will be used even after changes to the repository.
+
 5. It must accept command arguments. The Dockerfile will effectively be launched as:
 
-   ```
+   ```shell
    docker run <image> jupyter notebook <arguments from the mybinder launcher>
    ```
 
@@ -179,6 +178,40 @@ For a Dockerfile to work on Binder, it must meet the following requirements:
 
    For more information, and a shell wrapper example, please see the [Dockerfile best practices: ENTRYPOINT](<https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#entrypoint>) documentation.
 
+You can build and test your image locally like this.
+
+1. Try building your image.
+
+   ```shell
+   docker build -t my-image .
+   ```
+
+2. Try starting a container from the image.
+
+   ```shell
+   docker run -it --rm -p 8888:8888 my-image jupyter-notebook --ip=0.0.0.0 --port=8888
+   ```
+
+3. Inspect the container from terminal.
+
+   Verify your user has an id of `1000` and ownership of files in the home folder.
+
+   ```shell
+   docker run -it --rm my-image bash
+   ```
+
+   ```shell
+   # what username do i have?
+   whoami
+   # what user id do i have?
+   id -u
+   # what is the current working directory?
+   pwd
+   # who is the owner of the files in the users home directory?
+   ls -alh ~
+   ```
+
+
 ## Ensuring reproducibility with Dockerfiles
 
 Ensuring that your Binder environment is reproducible requires extra