Merge pull request #375 from betatim/start-script-docs

Split out tests, tweak docs, and a style change

docs/source/config_files.rst

@@ -117,7 +117,7 @@ repo2docker **requires configuration files such as** ``environment.yml`` or
 A script that can contain arbitrary commands to be run after the whole repository has been built. If you
 want this to be a shell script, make sure the first line is ```#!/bin/bash``.
 
-An example usecase of ``postBuild`` file is JupyterLab's demo on mybinder.org.
+An example use-case of ``postBuild`` file is JupyterLab's demo on mybinder.org.
 It uses a ``postBuild`` file in a folder called ``binder`` to `prepare
 their demo for binder <https://github.com/jupyterlab/jupyterlab-demo/blob/master/binder/postBuild>`_.
 
@@ -126,12 +126,18 @@ their demo for binder <https://github.com/jupyterlab/jupyterlab-demo/blob/master
 ``start``
 ^^^^^^^^^
 
-A script that can contain arbitrary commands to be run at runtime (as an
+A script that can contain simple commands to be run at runtime (as an
 `ENTRYPOINT <https://docs.docker.com/engine/reference/builder/#entrypoint>`
 to the docker container). If you want this to be a shell script, make sure the
 first line is ```#!/bin/bash``. The last line must be ```exec "$@"```
 equivalent.
 
+Use this to set environment variables that software installed in your container
+expects to be set. This script is executed each time your binder is started and
+should at most take a few seconds to run.
+
+If you only need to run things once during the build phase use :ref:`postBuild`.
+
 .. TODO: Discuss runtime limits, best practices, etc.
    Also, point to an example.
 

repo2docker/buildpacks/base.py

@@ -132,7 +132,7 @@ RUN ./{{ s }}
 {% endif -%}
 
 # Add start script
-{% if start_script -%}
+{% if start_script is not none -%}
 RUN chmod +x "{{ start_script }}"
 ENTRYPOINT ["{{ start_script }}"]
 {% endif -%}
@@ -331,8 +331,8 @@ class BuildPack:
         """
         An ordered list of executable scripts to execute after build.
 
-        Is run as a non-root user, and must be executable. Used for doing
+        Is run as a non-root user, and must be executable. Used for performing
-        things that are currently not supported by other means!
+        build time steps that can not be perfomed with standard tools.
 
         The scripts should be as deterministic as possible - running it twice
         should not produce different results!
@@ -341,18 +341,18 @@ class BuildPack:
 
     def get_start_script(self):
         """
-        An ordered list of executable scripts to be executated at runtime.
+        The path to a script to be executated at container start up.
-        These scripts are added as an `ENTRYPOINT` to the container.
 
-        Is run as a non-root user, and must be executable. Used for doing
+        This script is added as the `ENTRYPOINT` to the container.
-        things that are currently not supported by other means and need to be
-        applied at runtime (set environment variables).
 
-        The scripts should be as deterministic as possible - running it twice
+        It is run as a non-root user, and must be executable. Used for performing
+        run time steps that can not be perfomed with standard tools. For example
+        setting environment variables for your repository.
+
+        The script should be as deterministic as possible - running it twice
         should not produce different results.
-
         """
-        return ''
+        return None
 
     def binder_path(self, path):
         """Locate a file"""
@@ -546,4 +546,4 @@ class BaseImage(BuildPack):
         start = self.binder_path('start')
         if os.path.exists(start):
             return start
-        return ''
+        return None

tests/venv/start/start-script/README.rst

@@ -0,0 +1,8 @@
+System - launch scripts
+-----------------------
+
+It is possible to run `start` scripts before your notebook server starts.
+This is useful to set environment variables or perform last minute
+configurations.
+
+In this example we set a environment variable in the `start` script.

tests/venv/start/start-script/verify

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -euo pipefail
+
+if [ "$TEST_START_VAR" != "var is set" ]
+then
+  echo "TEST_START_VAR is not set"
+  exit 1
+fi