Merge pull request #363 from jhamman/feature/launch_script

Add launch script

Author: betatim

docs/source/config_files.rst

@@ -121,6 +121,20 @@ An example usecase 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>`_.
 
+.. _start:
+
+``start``
+^^^^^^^^^
+
+A script that can contain arbitrary 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.
+
+.. TODO: Discuss runtime limits, best practices, etc.
+   Also, point to an example.
+
 .. _runtime.txt:
 
 ``runtime.txt``

docs/source/dev_newbuildpack.md

@@ -23,4 +23,4 @@ Note that this doesn't apply to adding additional libraries / UI to existing
 buildpacks. For example, if we had an R buildpack and it supported IRKernel,
 it is much easier to
 just support RStudio / Shiny with it, since those are library additions than entirely
-new buildpacks.
+new buildpacks.

repo2docker/buildpacks/base.py

@@ -131,6 +131,12 @@
 {% endfor %}
 {% endif -%}
 
+# Add start script
+{% if start_script -%}
+RUN chmod +x "{{ start_script }}"
+ENTRYPOINT ["{{ start_script }}"]
+{% endif -%}
+
 # Specify the default command to run
 CMD ["jupyter", "notebook", "--ip", "0.0.0.0"]
 
@@ -333,6 +339,21 @@ def get_post_build_scripts(self):
         """
         return []
 
+    def get_start_script(self):
+        """
+        An ordered list of executable scripts to be executated at runtime.
+        These scripts are added as an `ENTRYPOINT` to the container.
+
+        Is run as a non-root user, and must be executable. Used for doing
+        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
+        should not produce different results.
+
+        """
+        return ''
+
     def binder_path(self, path):
         """Locate a file"""
         if os.path.exists('binder'):
@@ -380,6 +401,7 @@ def render(self):
             build_script_files=self.get_build_script_files(),
             base_packages=sorted(self.get_base_packages()),
             post_build_scripts=self.get_post_build_scripts(),
+            start_script=self.get_start_script(),
             appendix=self.appendix,
         )
 
@@ -519,3 +541,9 @@ def get_post_build_scripts(self):
         if os.path.exists(post_build):
             return [post_build]
         return []
+
+    def get_start_script(self):
+        start = self.binder_path('start')
+        if os.path.exists(start):
+            return start
+        return ''

tests/venv/start/postBuild/README.rst

@@ -0,0 +1,8 @@
+System - Post-build scripts
+---------------------------
+
+It is possible to run scripts after you've built the environment specified in
+your other files. This could be used to, for example, download data or run
+some configuration scripts.
+
+In this example, we download and install a Jupyter Notebook extension.

tests/venv/start/postBuild/postBuild

@@ -0,0 +1,2 @@
+#!/bin/bash
+jupyter nbextension enable --py --sys-prefix ipyleaflet

tests/venv/start/postBuild/requirements.txt

@@ -0,0 +1 @@
+ipyleaflet

tests/venv/start/postBuild/start

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+export TEST_START_VAR="var is set"
+
+exec "$@"

tests/venv/start/postBuild/verify

@@ -0,0 +1,9 @@
+#!/bin/bash
+set -euo pipefail
+jupyter nbextension list | grep 'jupyter-leaflet' | grep enabled
+
+if [ "$TEST_START_VAR" != "var is set" ]
+then
+  echo "TEST_START_VAR is not set"
+  exit 1
+fi