Loading...

Evolution of a Makefile for building projects with Docker

It's hard to move to GitLab and resist the temptation of its integrated GitLab CI. And with GitLab CI, it's just natural to run all CI jobs in Docker containers. Yet, to avoid vendor lock of its integrated Docker support, we choosed to keep our .gitlab-ci.yml configurations minimal and do all Docker calls with GNU make instead. This also ensured, that all of our CI tasks remain locally reproducible. In addition, we wanted to use official upstream Docker images from the official hub as far as possible.

As always with make, it it's a danger that Makefiles themselves become projects of their own. So, let's begin with a completely hypothetical Makefile:

all: test

test:
     karma test

.PHONY: all test
https://4.bp.blogspot.com/-upjVr6G_zGY/VyR85K0lLRI/AAAAAAAAAww/Il9BZ2gELggcRmIcdHFQncwaO5OT7WEUACKgB/s1600/IMG_0370.JPG

Separation of concerns

At first, we want to keep all Docker related commands separate from the actual project specific commands. This lead us to have two separate Makefiles. A traditional default one, which expects all the build tools and other dependencies to exist in the running system, and a Docker specific one. We named them Makefile (as already seen above) and Makefile.docker (below):

all: test

test:
     docker run --rm -v $PWD:/build -w /build node:5 make test

.PHONY: all test

So, we simply run a Docker container of required upstream language image (here Node 5), mount our project into the container and run make for the default Makefile inside the container.

$ make -f Makefile.docker

Of course, the logical next step is to abstract that Docker call into a function to make it trivial to wrap also other make targets to be run in Docker:

make = docker run --rm -v $PWD:/build -w /build node:5 make $1

all: test

test:
     $(call make,test)

.PHONY: all test

Docker specific steps in the main Makefile

In the beginning, I mentioned, that we try to use the official upstream Docker images whenever possible, to keep our Docker dependencies fresh and supported. Yet, what if we need just minor modifications to them, like installation of a couple of extra packages...

Because our Makefile.docker mostly just wraps the make call for the default Makefile into a auto-removed Docker container run (docker run --rm), we cannot easily install extra packages into the container in Makefile.docker. This is the exception, when we add Docker-related commands into the default Makefile.

There are probably many ways to detect the run in Docker container, but my favourite is testing the existence of /.dockerenv file. So, any Docker container specific command in Makefile is wrapped with test for that file, as in:

all: test

test:
     [ -f /.dockerenv ] && npm -g i karma || true
     karma test

.PHONY: all test

Getting rid of the filesystem side-effects

Unfortunately, one does not simply mount a source directory from the host into a container and run arbitrary commands with arbitrary users with that mount in place. (Unless one wants to play to game of having matching user ids inside and outside the container.)

To avoid all issues related to Docker possibly trying to (and sometimes succeeding in) creating files into mounted host file system, we may run Docker without host mount at all, by piping project sources into the container:

make = git archive HEAD | \
       docker run -i --rm -v /build -w /build node:5 \
       bash -c "tar x --warning=all && make $1"

all: test

test: bin/test
     $(call make,test)

.PHONY: all test
  • git archive HEAD writes tarball of the project git repository HEAD (latest commit) into stdout.
  • -i in docker run enables stdin in Docker.
  • -v /build in docker run ensures /build to exist in container (as a temporary volume).
  • bash -c "tar x --warning=all && make $1" is the single command to be run in the container (bash with arguments). It extracts the piped tarball from stdin into the current working directory in container (/build) and then executes given make target from the extracted tarball contents' Makefile.

Caching dependencies

One well known issue with Docker based builds is the amount of language specific dependencies required by your project on top of the official language image. We've solved this by creating a persistent data volume for those dependencies, and share that volume from build to build.

For example, defining a persistent NPM cache in our Makefile.docker would look like this:

CACHE_VOLUME = npm-cache

make = git archive HEAD | \
       docker run -i --rm -v $(CACHE_VOLUME):/cache \
       -v /build -w /build node:5 \
       bash -c "tar x --warning=all && make \
       NPM_INSTALL_ARGS='--cache /cache --cache-min 604800' $1"

all: test

test: bin/test
     $(INIT_CACHE)
     $(call make,test)

.PHONY: all test

INIT_CACHE = \
    docker volume ls | grep $(CACHE_VOLUME) || \
    docker create --name $(CACHE_VOLUME) -v $(CACHE_VOLUME):/cache node:5
  • CACHE_VOLUME variable holds the fixed name for the shared volume and the dummy container keeping the volume from being garbage collected by docker run --rm.
  • INIT_CACHE ensures that the cache volume is always present (so that it can simply be removed if its state goes bad).
  • -v $(CACHE_VOLUME:/cache in docker run mounts the cache volume into test container.
  • NPM_INSTALL_ARGS='--cache /cache --cache-min 604800' in docker run sets a make variable NPM_INSTALL_ARGS with arguments to configure cache location for NPM. That variable, of course, should be explicitly defined and used in the default Makefile:
NPM_INSTALL_ARGS =

all: test

test:
     @[ -f /.dockerenv ] && npm -g $(NPM_INSTALL_ARGS) i karma || true
     karma test

.PHONY: all test

Cache volume, of course, adds state between the builds and may cause issues that require resetting the cache containers when that hapens. Still, most of the time, these have been working very well for us, significantly reducing the required build time.

Retrieving the build artifacts

The downside of running Docker without mounting anything from the host is that it's a bit harder to get build artifacts (e.g. test reports) out of the container. We've tried both stdout and docker cp for this. At the end we ended up using dedicated build data volume and docker cp in Makefile.docker:

CACHE_VOLUME = npm-cache
DOCKER_RUN_ARGS =

make = git archive HEAD | \
       docker run -i --rm -v $(CACHE_VOLUME):/cache \
       -v /build -w /build $(DOCKER_RUN_ARGS) node:5 \
       bash -c "tar x --warning=all && make \
       NPM_INSTALL_ARGS='--cache /cache --cache-min 604800' $1"

all: test

test: DOCKER_RUN_ARGS = --volumes-from=$(BUILD)
test: bin/test
     $(INIT_CACHE)
     $(call make,test); \
       status=$$?; \
       docker cp $(BUILD):/build .; \
       docker rm -f -v $(BUILD); \
       exit $$status

.PHONY: all test

INIT_CACHE = \
    docker volume ls | grep $(CACHE_VOLUME) || \
    docker create --name $(CACHE_VOLUME) -v $(CACHE_VOLUME):/cache node:5

# http://cakoose.com/wiki/gnu_make_thunks
BUILD_GEN = $(shell docker create -v /build node:5
BUILD = $(eval BUILD := $(BUILD_GEN))$(BUILD)

A few powerful make patterns here:

  • DOCKER_RUN_ARGS = sets a placeholder variable for injecting make target specific options into docker run.
  • test: DOCKER_RUN_ARGS = --volumes-from=$(BUILD) sets a make target local value for DOCKER_RUN_ARGS. Here it adds volumes from a container uuid defined in variable BUILD.
  • BUILD is a lazily evaluated Make variable (created with GNU make thunk -pattern). It gets its value when it's used for the first time. Here it is set to an id of a new container with a shareable volume at /build so that docker run ends up writing all its build artifacts into that volume.
  • Because make would stop its execution after the first failing command, we must wrap the make test call of docker run so that we
    1. capture the original return value with status=$$?
    2. copy the artifacts to host using docker cp
    3. delete the build container
    4. finally return the captured status with exit $$status.

This pattern may look a bit complex at first, but it has been powerful enough to start any number of temporary containers and link or mount them with the actual test container (similarly to docker-compose, but directly in Makefile). For example, we use this to start and link Selenium web driver containers to be able run Selenium based acceptance tests in the test container on top of upstream language base image, and then retrieve the test reports from the build container volume.

Building a Plone form widget with React + Redux

As much I love the new through-the-web resource registries in Plone 5 (I really do), for the current Plone 5 sites in development or already in production, I've ended up bundling all front-end resources into theme with Webpack. That gives me the same "state of art" frontend toolchain to other current projects, but also adds some overhead, because I need to do extra work for each new add-on with front-end resources. So, I still cannot really recommend Webpack for Plone, unless you are already familiar with Webpack. Yet, learning to bundle everything with Webpack really helps to appreciate, how well Plone 5 resource registries already work.

My current workflow, in brief, is to add all common configration into plonetheme.webpack and re-use that as a git submodule in individual projects, similarly to plonetheme.webpackexample. The latter also includes the example code for this post. I was asked, how everything goes together when using React and Redux for building widgets for Plone. Here's how...

(You can see the complete example in plonetheme.webpackexample, particuarly in 1 and 2.)

Injecting a pattern with Diazo

In a usual use case, I have a custom content type (maybe TTW designed) with simple textline or lines (textarea) fields, which require rich JavaScript widgets to ease entering of valid input.

The current Plone convention for such widgets is to implement the widget as a Patternslib compatible pattern. The required classname (and options) for the pattern initialization could, of course, be injected by registering a custom z3c.form widget for the field, but it can also be done with a relatively simple Diazo rule with some XSLT:

<!-- Inject license selector pattern -->
<replace css:content="textarea#form-widgets-IDublinCore-rights">
  <xsl:copy>
    <xsl:attribute name="class">
      <xsl:value-of select="concat(@class, ' pat-license-selector')" />
    </xsl:attribute>
    <xsl:apply-templates select="@*[name()!='class']|node()" />
  </xsl:copy>
</replace>

Registering a pattern in ES6

Of course, you cannot yet use ES6 in Plone without figuring out a way to way to transpile it into JavaScript currently supported by your target browsers and RequireJS (that something, which comes quite easily with Webpack). If you can do it, registering a Patternslib compatible pattern in ES6 appeared to be really simple:

import Registry from 'patternslib/core/registry';

// ... (imports for other requirements)

Registry.register({

  name: 'license-selector',
  trigger: '.pat-license-selector',

  init ($el, options) {
    // ... (pattern code)
  }
});

Choosing React + Redux for widgets

You must have already heard about the greatest benefits in using React as a view rendering library: simple unidirectional data flow with stateless views and pretty fast rendering with "shadow DOM" based optimization. While there are many alternatives for React now, it probably has the best ecosystem, and React Lite-like optimized implementations, make it small enough to be embeddable anywhere.

Redux, while technically independent from React, helps to enforce the React ideals of predictable stateless views in your React app. In my use case of building widgets for individual input fields, it feels optimal because of its "single data store model": It's simple to both serialize the widget value (Redux store state) into a single input field and de-serialize it later from the field for editing.

Single file React + Redux skeleton

Even that Redux is very small library with simple conventions, it seems to be hard to find an easy example for using it. That's because most of the examples seem to assume that you are building a large scale app with them. Yet, with a single widget, it would be nice to have all the required parts close to each other in a single file.

As an example, I implemented a simple Creative Commons license selector widget, which includes all the required parts of React + Redux based widget in a single file (including Patternslib initialization):

import React from 'react';
import ReactDOM from 'react-dom';
import {createStore, compose} from 'redux'
import Registry from 'patternslib/core/registry';

// ... (all the required imports)
// ... (all repeating marker values as constants)

function deserialize(value) {
  // ... (deserialize value from field into initial Redux store state)
}

function serialize(state) {
  // ... (serialize value Redux store state into input field value)
}

function reducer(state={}, action) {
  // ... ("reducer" to apply action to state and return new state)
}

export default class LicenseSelector extends React.Component {
  render() {
    // ...
  }
}

LicenseSelector.propTypes = {
  // ...
};

// ... (all the required React components with property annotations)

Registry.register({
  name: 'license-selector',
  trigger: '.pat-license-selector',

  init ($el) {
    // Get form input element and hide it
    const el = $el.hide().get(0)

    // Define Redux store and initialize it from the field value
    const store = createStore(reducer, deserialize($el.val()));

    // Create container for the widget
    const container = document.createElement('div');
    el.parentNode.insertBefore(container, el);
    container.className = 'license-selector';

    // Define main render
    function render() {
      // Serialize current widget value back into input field
      $el.val(serialize(store.getState()));

      // Render widget with current state
      ReactDOM.render((
        <LicenseSelector
          // Pass state
          {...store.getState()}
          // Pass Redux action factories
          setSharing={(value) => store.dispatch({
            type: SET_SHARING,
            value: value
          })}
          setCommercial={(value) => store.dispatch({
            type: SET_COMMERCIAL,
            value: value
          })}
          />
      ), container);
    }

    // Subscribe to render when state changes
    store.subscribe(render);

    // Call initial render
    render();
  }
});

Not too complex, after all...

Implementing and injecting a display widget as a themefragment

Usually displaying value from a custom field requires more HTML that's convenient to inline into Diazo rules, and may also require data, which is not rendered by the default Dexterity views. My convention for implementing these "display widgets" in theme is the following combination of theme fragments and Diazo rules.

At first, I define a theme fragment. Theme fragments are simple TAL templates saved in ./fragments folder inside a theme, and are supported by installing collective.themefragments add-on. My example theme has the following fragment at ./fragments/license.pt:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:tal="http://xml.zope.org/namespaces/tal">
<body>
<p tal:condition="context/rights|undefined">
  <img src="https://i.creativecommons.org/l/${context/rights}/4.0/88x31.png"
       alt="${context/rights}" />
</p>
</body>
</html>

Finally, the fragment is injected into desired place using Diazo. In my example, I use Diazo inline XSLT to append the fragment into below content viewlets' container:

<!-- Inject license badge below content body -->
<replace css:content="#viewlet-below-content-body"
         css:if-not-content="textarea#form-widgets-IDublinCore-rights">
  <xsl:copy>
    <xsl:apply-templates select="@*|node()" />
    <xsl:copy-of select="document('@@theme-fragment/license',
                         $diazo-base-document)/html/body/*" />
  </xsl:copy>
</replace>

Building Plone theme with Webpack

I just fixed my old post on customizing Plone 5 default theme on the fly to work with the final Plone 5.0 release.

But if you could not care less about TTW (through-the-web) theme development, here's something for you too: it is possible to build a theme for Plone 5 with all Plone 5's stylesheets and javascripts using Webpack รข€“ the current tool of choice for bundling web app frontent resources.

With Webpack, you can completely ignore Plone 5's TTW resource registry, and build your own optimal CSS and JS bundles with all the mockup patterns and other JS frameworks you need - with live preview during development.

To try it out, take a look at my WIP example theme at: https://github.com/datakurre/plonetheme.webpack

Pros:

  • Ship your theme with Webpack-optimized resource chunks automatically split into synchronous and asynchronously required resources.
  • Get faster-than-reload live previews of your changes during development thanks to Webpack's development server's hot module replacement support.
  • Get complete control of Plone 5 frontend resources and completely bypass Plone 5 TTW resource registry (it's awesome for TTW workflow, but not optimal for thefilesystem one).
  • Use the latest JS development tools (Webpack integrates nicely with Babel, ESLint and others) without need for legacy Bower, Grunt, Gulp or RequireJS.

Cons:

  • Installing a new Plone add-on requires configuring and building add-on's resources into theme.
  • You are on your own now, because you no longer get JS / CSS updates with new Python package releases, but you always need to also re-build your theme.

Nix in Docker – Best of Both Worlds

I'm using Nix mostly on a mac as a development tool, and every now and then I get blocked by some packages not working on OS X.

For those situations I've been working for my own Nix image for Docker: A such minimal Docker image that it only contains the files from the Nix installer, but could re-use persistent shared Nix-installation between Docker containers to make itself fast, convenient and lean.

My build recipe is now available at:

Features:

  • A single Docker image, which can be used to run anything from nixpkgs.
  • You can nix-shell -p to get a Docker isolated development shell with all your requirements installed from nixpkgs.
  • You can -v /my/path:/var/nixpkgs to use your own nixpkgs clone.
  • You can -v /my/path:/etc/nix to use your own nix configuration.
  • With the shared data container:
    • Sequential and simultaneous containers can share the same Nix installation.
    • You can nix-env -i to add new commands (or manage custom profiles).
    • You can nix-collect-garbage -d to clean up the data container.
  • You can use it as a base image and add new stuff with nix-env -i.

Bootstrapping

Build a Docker image named nix using the provided Docker based build chain:

$ git clone https://gist.github.com/datakurre/a5d95794ce73c28f6d2f
$ cd a5d95794ce73c28f6d2f
$ make

Create a Docker data container named nix to use a shared persistent /nix for all your Nix containers:

$ docker create --name nix -v /nix nix sh

To know more about where the nix data gets stored with this setup, please, read Docker documentation about managing data in containers.

Examples of use

Running a Python interpreter with some packages:

$ docker run --rm --volumes-from=nix -ti nix \
         nix-shell -p python35Packages.pyramid --run python3

Running a Python Jupyter notebook with mounted context:

$ mkdir .jupyter
$ echo "c.NotebookApp.ip = '*'" > .jupyter/jupyter_notebook_config.py
$ docker run --rm --volumes-from=nix -ti \
         -v $PWD:/mnt -w /mnt -e HOME=/mnt -p 8888 nix \
         nix-shell -p python35Packages.notebook --run "jupyter notebook"

Running a Haskell Jupyter notebook with mounted context:

$ mkdir .jupyter
$ echo "c.NotebookApp.ip = '*'" > .jupyter/jupyter_notebook_config.py
$ docker run --rm --volumes-from=nix -ti \
         -v $PWD:/mnt -w /mnt -e HOME=/mnt -p 8888 nix \
         nix-shell -p ihaskell --run "ihaskell-notebook"

Running development shell for default.nix in mounted context:

Adding --help for nix-commands:

$ docker run --rm --volumes-from=nix nix nix-env -i man
$ docker run --rm --volumes-from=nix nix nix-env --help

Purging nix-store cache:

$ docker run --rm --volumes-from=nix nix nix-collect-garbage -d

Using the image as a base for a new Docker image, with ./Dockerfile:

FROM nix
RUN nix-env -i python
ENTRYPOINT ["/usr/local/bin/python"]
$ docker build -t python --rm=true --force-rm=true --no-cache=true .
$ docker run --rm -ti python

Creating Jupyter Docker-containers with Nix

Jupyter is the new name and brand for an awesome interactive data science programming scratchpad previously known as iPython Notebook. While there are plenty of pre-built Docker images available for Jupyter, for customized images, I'm tempted to use Nix.

Here I describe approach for the following gists creating

Note: Because these Jupyter notebook configurations are build with Nix, their configuration is immutable and it's not possible for the user to install any additional packages directly from a notebook.

http://4.bp.blogspot.com/-qCDD1d_bCRw/VkXVCBC-P0I/AAAAAAAAAqs/9HiAnQ5TFZo/s1600/jupyter.png

Usage

With nix-shell (unless you are on a mac):

$ git clone https://gist.github.com/datakurre/49b6fbc4bafdef029183
$ cd 49b6fbc4bafdef029183
$ nix-shell --run "jupyter notebook"

With Docker (works also on a mac):

$ git clone https://gist.github.com/datakurre/49b6fbc4bafdef029183
$ cd 49b6fbc4bafdef029183
$ make run

Now, if you are on a mac, you need to figure out the IP and port where notebook is running with:

$ docker-machine ip default
$ docker ps

Explanation

At first, both of my Jupyter gists are based on my recipe for building Docker containers with Nix.

It builds a Docker image with Nix installation to build your Nix expressions, creates a nix store data container to store and share built Nix expressions between builds, and creates a Docker ready tarball from a built nix closure.

Then a few picks from the expressions:

with import <nixpkgs> {};
let dependencies = rec {
  # ...
  jupyter = python35Packages.notebook.override {
    postInstall = with python35Packages; ''
      mkdir -p $out/bin
      ln -s ${jupyter_core}/bin/jupyter $out/bin
      wrapProgram $out/bin/jupyter \
        --prefix PYTHONPATH : "${notebook}/lib/python3.5/site-packages:$PYTHONPATH" \
        --prefix PATH : "${notebook}/bin:$PATH"
    '';
  };
# ...
}

To be able to run Jupyter notebook, I want to use the normal jupyter command, but a problem is that the base command is defined in a python package jupyter_core, which does not include notebook-package, which includes the actual Jupyter notebook program and its jyputer notebook subcommand. The Nix solution is to install notebook package, but enhance its install with a custom postinstall, whick links the command from jupyter_core and wraps the command to be aware of notebook and itse dependencies.

with import <nixpkgs> {};
let dependencies = rec {
  builder = builtins.toFile "builder.sh" ''
    source $stdenv/setup
    mkdir -p $out
    cat > $out/kernel.json << EOF
    $json
    EOF
  '';
  # ...
  python34 = pkgs.python34.buildEnv.override {
    extraLibs = with python34Packages; [
      # Kernel
      ipykernel
      ipywidgets
      # Custom packages
      lightning
      # ...
    ];
  };
  python34_kernel = stdenv.mkDerivation rec {
    name = "python34";
    buildInputs = [ python34 ];
    json = builtins.toJSON {
      argv = [ "${python34}/bin/python3.4"
               "-m" "ipykernel" "-f" "{connection_file}" ];
      display_name = "Python 3.4";
      language = "python";
      env = { PYTHONPATH = ""; };
    };
    inherit builder;
  };
# ...
}

Next I want to be able to define and configure as many Jupyter kernels as I need in my notebook. This pattern first defines the kernel environment. Above that is Python 3.4 with the mandatory iPython packages and then any amount of Python packages I want to provide for the notebook.

The second part of the pattern just defines an iPython kernel configuration (usually created using jupyter kernelspec in mutable Jupyter installations) so that the kernel uses our previously defined Python 3.4 environment. The builder for actually creating the configuration file is defined an upper level of the expression so that it can easily be re-used with inherit builder;.

With this approach, is possible to have as many different and differently configured kernels as you want. It's possible to have both Python 3.4 and 3.5 or many different configurations for the same version. For example, when there's a major upgrade in some package, it's possible to have one kernel with the old version and another with the new version.

The example gists also include similarly configurable kernel configuration for R.

with import <nixpkgs> {};
let dependencies = rec {
  # ...
  jupyter_config_dir = stdenv.mkDerivation {
    name = "jupyter";
    buildInputs = [
      python34_kernel
      R_kernel
    ];
    builder = writeText "builder.sh" ''
      source $stdenv/setup
      mkdir -p $out/etc/jupyter/kernels $out/etc/jupyter/migrated
      ln -s ${python34_kernel} $out/etc/jupyter/kernels/${python34_kernel.name}
      ln -s ${R_kernel} $out/etc/jupyter/kernels/${R_kernel.name}
      cat > $out/etc/jupyter/jupyter_notebook_config.py << EOF
      import os
      c.KernelSpecManager.whitelist = {
        '${python34_kernel.name}',
        '${R_kernel.name}'
      }
      c.NotebookApp.ip = os.environ.get('JUPYTER_NOTEBOOK_IP', 'localhost')
      EOF
    '';
  };
  # ...
};

The next most important part is the expression to compose all the defined kernels into a compelete and immutable Jupyter configuration directory. Whitelisting kernels in configuration is required to hide the Python environment running the Jupyter notebook (because it only has the notebook dependencies and is missing all the interesting libraries). The line with c.NotebookApp.ip allows Docker to configure notebook to allow connections outside the container.

with import <nixpkgs> {};
let dependencies = rec {
  # ...
};
in with dependencies;
stdenv.mkDerivation rec {
  name = "jupyter";
  env = buildEnv { name = name; paths = buildInputs; };
  builder = builtins.toFile "builder.sh" ''
    source $stdenv/setup; ln -s $env $out
  '';
  buildInputs = [
    jupyter
    jupyter_config_dir
  ] ++ stdenv.lib.optionals stdenv.isLinux [ bash fontconfig tini ];
  shellHook = ''
    mkdir -p $PWD/.jupyter
    export JUPYTER_CONFIG_DIR=${jupyter_config_dir}/etc/jupyter
    export JUPYTER_PATH=${jupyter_config_dir}/etc/jupyter
    export JUPYTER_DATA_DIR=$PWD/.jupyter
    export JUPYTER_RUNTIME_DIR=$PWD/.jupyter
  '';
}

Finally, we define an buildable environment installation, which mainly includes Jupyter (command) and its configuration. On Linux a few extra dependencies are added to make Jupyter run in a Docker container. For nix-shell command the expression configures Jupyter to look configuration from the Nix built configuration directory and store volatile runtime files under the current working directory.

Environment variables are also the way to configure Jupyter to run properly in a Docker container. My Dockerfile configures Jupyter to look configuration from the directory created by my recipe for building Docker containers with Nix, and store volatile runtime files under the host directory mounted as /mnt. In my example Makefile that's configured to be the current working directory, which is also used shown as the notebook home directory.

FROM scratch
ADD default.nix.tar.gz /
ENV FONTCONFIG_FILE="/etc/fonts/fonts.conf" \
    JUPYTER_NOTEBOOK_IP="*" \
    JUPYTER_CONFIG_DIR="/etc/jupyter" \
    JUPYTER_PATH="/etc/jupyter" \
    JUPYTER_DATA_DIR="/mnt/.jupyter" \
    JUPYTER_RUNTIME_DIR="/mnt/.jupyter"
EXPOSE 8888
ENTRYPOINT ["/bin/tini", "--", "/bin/jupyter"]

Note: Running Jupyter notebook in Docker container may require tini (or supervisor) to allow Jupyter spawn all the kernel processes it needs within the container.

Nix for Python developers

About a week ago, I had the pleasure of giving a presentation about my Nix experiences at PyCon Finland 2015. This is an executive afterthought summary of that presentation, focusing only on how to use Nix to build development environments. With a few cool additional examples.

Installing Nix

The easiest way to install Nix for development usage is the default single user installation:

$ sudo mkdir /nix
$ bash <(curl https://nixos.org/nix/install)

The default installation of Nix would install and build everything under that /nix, which makes it easy to uninstall Nix at any point by simply deleting that directory. It also comes configured for the latest nixpkgs release. (Nix is just the generic build system and package manager, nixpkgs is the recommended community managed package collection for it.)

After a successful installation, available packages can searched with:

nix-env -qaP|grep -i needle

Alternative installation methods would be to follow that installer script manually, build Nix from source or request your Linux distribution to package it for you. Read more about all the options and basic Nix usage at Nix Package Manager Guide. Building Nix from source would allow to choose where stores the build (other place than /nix), but that would also prevent it using the community binary caches (by default Nix tries to download builds from the community binary cache at first and only then build them locally).

Next you want to create a Nix configuration file /etc/nix/nix.conf with the following content of a couple of special configuration flags:

gc-keep-outputs = true
build-use-chroot = true

Option gc-keep-outputs = true will configure Nix garbage collector to be more developer friendly by not collecting build-time-only dependencies so easily. Option build-use-chroot will trigger isolated builds to ensure that nothing from your existing system can affect Nix builds.

At any point of Nix use, you could clean up /nix and possibly free some disk space by simply running its garbage collector:

$ nix-collect-garbage -d

Never ever manually remove files from /nix unless you are completely uninstalling it.

Nix offically supports Linux and OS X. Yet, if you are using OS X, you should read special instructions from the wiki for OS X. The OS X support has been in heavy development lately and not all available packages build yet on OS X. In addition to reading thw wiki page, you want to add the following lines into /etc/nix/nix.conf to ensure that Nix uses all available binary builds also on OS X:

binary-caches = https://cache.nixos.org https://hydra.nixos.org
use-binary-caches = true

For all OS X related Nix issues, you can get help from ##nix-darwin channel at Freenode IRC network.

The community members told me having used Nix also on Cygwin, FreeBSD, OpenBSD, NetBSD, OpenSolaris and SmartOS. Yet, on other systems, you would need to learn more about how nixpkgs work to get on of its standard build environments to work on your system.

Using Nix

Finally, let the fun begin:

Run anything with a one-liner

nix-shell can be used to run anything available in nixpkgs simply with:

$ nix-shell -p package --run "command"

For example:

$ nix-shell -p python35 --run "python3"

Or:

$ nix-shell -p redis --run "redis-server"
$ nix-shell -p nodejs --run "node"
$ nix-shell -p graphviz --run "dot -V"
$ nix-shell -p texLive --run "pdflatex --help"

Or with any number of packages:

$ nix-shell -p redis -p python35Packages.redis --run "python3"

Nix would simply either downloard or build all the defined packages, build a combined environment with all of them and then execute the given command in that environment. Everything would be installed under /nix and cleaned by garbage collector with nix-collect-garbage -d.

Get into shell with anything with a one-liner

Calling nix-shell without --run would drop you into an interactive shell with the required dependencies:

$ nix-shell -p texLive -p gnumake -p redis -p python35

Entering exit would exit the shell as usual.

Additionally, adding --pure into nix-shell arguments, would limit PATH and other environment variables to only include the listed packges while inside the shell.

Define script dependencies in a hashbang

nix-shell can also be used in a shell script hashbang line to execute the script in an environment with any required dependencies:

#! /usr/bin/env nix-shell
#! nix-shell -i python3 -p python35Packages.tornado -p nodejs

The first line #! /usr/bin/env nix-shell is a standard hasbang-line, but with nix-shell it can follow any number of #! nix-shell lines defining the required dependencies using nix-shell command line arguments.

The most common arguments for nix-shell in hashbang use are:

  • -p to define packages available in the execution environment
  • -i to define the interpreter command (from listed packages) used to actually run the script.

More examples are available in the Nix manual.

Build complex development environments with Nix expressions

When one-liners are not enough, it's possible to define a more complete development environment using the functional Nix expression language. Both nix-shell and nix-build can take a file with such expression as their first optional positional argument. Also both look for a file named ./default.nix by default.

You could use the following example as the base for your ./default.nix:

with import <nixpkgs> {};
stdenv.mkDerivation rec {
  name = "env";

  # Mandatory boilerplate for buildable env
  env = buildEnv { name = name; paths = buildInputs; };
  builder = builtins.toFile "builder.sh" ''
    source $stdenv/setup; ln -s $env $out
  '';

  # Customizable development requirements
  buildInputs = [
    # Add packages from nix-env -qaP | grep -i needle queries
    redis

    # With Python configuration requiring a special wrapper
    (python35.buildEnv.override {
      ignoreCollisions = true;
      extraLibs = with python35Packages; [
        # Add pythonPackages without the prefix
        redis
        tornado
      ];
    })
  ];

  # Customizable development shell setup with at last SSL certs set
  shellHook = ''
    export SSL_CERT_FILE=${cacert}/etc/ssl/certs/ca-bundle.crt
  '';
}

Running

$ nix-build

would now create symlinked directory ./result with ./result/bin with both ./result/bin/redis and ./result/bin/python3 with redis and tornado as importable packages. That build is comparable to familiar Python virtualenv, but for any dependencies, not just Python packages.

The resulting Python interpreter ./result/bin/python3 could also be used with IDE, e.g. configured as a project interpreter for PyCharm.

The resulting directory name can be changed from result into something else with argument -o myname. The directory also works as a so called garbage collection root, which prevents Nix garbage collection from clearing it until the directory (symlink) has been renamed, moved or deleted.

Running

$ nix-shell

would enter into an interactive shell with all dependencies in path as expected.

Running

$ nix-shell --run "python3"

would start that Python interpreter defined in ./default.nix with tornado and redis packages (and also the redis server available in the process' environment).

Finally, to turn the environment into a distributable docker container, check my Nix to Docker build pack example at GitHub.

Add custom dependencies into a Nix expression

Sometimes, yet unfortunatley often with Python packages, not all your dependencies are defined in nixpkgs already. The best solution, of course, would be to make pull requests to add them there, but it's also possible to just define them per project in the very same project specific ./default.nix.

For example, let's upgrade tornado into its latest beta, and add a comeletely new Python package, redis_structures, with the following dependencies pattern:

with import <nixpkgs> {};
let dependencies = rec {

  # Customized existing packages using expression override
  _tornado = with python35Packages; tornado.override rec {
    name = "tornado-4.3b1";
    src = fetchurl {
      url = "https://pypi.python.org/packages/source/t/tornado/${name}.tar.gz";
      sha256 = "c7ddda61d9469c5745f3ac00e480ede0703dd1a4ef540a3d9bd5e03e9796e430";
    };
  };

  # Custom new packages using buildPythonPackage expression
  _redis_structures= with python35Packages; buildPythonPackage rec {
    name = "redis_structures-0.1.3";
    src = fetchurl {
      url = "https://pypi.python.org/packages/source/r/redis_structures/${name}.tar.gz";
      sha256 = "4076cff3ea91b7852052d963bfd2533c74e8a0054826584e058e685a911f56c5";
    };
    # Fix broken packaging (package is missing README.rst)
    prePatch = "touch README.rst";
    # Define package requirements (without pythonPackages prefix)
    propagatedBuildInputs = [ redis ];
  };
};
in with dependencies;
stdenv.mkDerivation rec {
  name = "env";

  # Mandatory boilerplate for buildable env
  env = buildEnv { name = name; paths = buildInputs; };
  builder = builtins.toFile "builder.sh" ''
    source $stdenv/setup; ln -s $env $out
  '';

  # Customizable development requirements
  buildInputs = [
    # Add packages from nix-env -qaP | grep -i needle queries
    redis

    # With Python configuration requiring a special wrapper
    (python35.buildEnv.override {
      ignoreCollisions = true;
      extraLibs = with python35Packages; [
        # Add pythonPackages without the prefix
        _tornado
        _redis_collections
      ];
    })
  ];

  # Customizable development shell setup with at last SSL certs set
  shellHook = ''
    export SSL_CERT_FILE=${cacert}/etc/ssl/certs/ca-bundle.crt
  '';
}

See the full explanation of buildPythonPackage-expression in nixpkgs manual.

Generating Nix expressions

The only real issue in using Nix with Python is that only a portion of packages released at PyPI are available in nixpkgs. And those, which are available, have usually only the latest version there.

If it would be trivial to generate Nix-expressions for all public Python packages, that would have already been done. Unfortunately, it's not and it's not been done. And it's not because of Nix, but because of the various imperfect ways how Python packages can define their dependencies.

I was told that things would get better once PEP426 is implemented and used in practice.

Nevertheless, there are many tools to try for generating and maintaining Nix expressions for Python packages and projects. Each of them may emphase different things and may or may not always produce directly usable expression:

Personally I'm using and developing only collective.recipe.nix, which is currently only usable out of the box for Python 2.7 projects, I'm working on support for Python 3.x projects and easier usage.

Full example project

Finally, let's try developing a demo Python 3.5 async / await HTTP-AMQP-bridge: a http-service, which distributes all the request to workers through AMQP broker. Just for fun:

$ git clone https://gist.github.com/datakurre/2076247049dabe16627f
$ cd 2076247049dabe16627f
$ ls -1
connection.py
default.nix
server.py
setup.py
supervisord.nix
worker.py

This project only has a few files:

./setup.py
to define the python package
./connection.py
to manage the AMQP connection and give a new channel when requested (AMQP channels are kind of virtual AMQP connections running on top of the one real connection)
./server.py
to run a tornado server to handle the incoming requests by passing them to AMQP broker and returning the result
./worker.py
to handle requests from AMQP broken and return the results back to the serer.
./default.nix
the nix expression to setup up a development environment with RabbitMQ and Python with required packages
./supervisord.nix
an alternative nix expression for setting an environment with pre-configured supervisord.

Let see the ./default.nix in detail:

with import <nixpkgs> {};
let dependencies = rec {
  _erlang = erlang.override { wxSupport = false; };
  _rabbitmq_server = rabbitmq_server.override { erlang = _erlang; };
  _enabled_plugins = builtins.toFile "enabled_plugins" "[rabbitmq_management].";
  _tornado = with python35Packages; tornado.override {
    name = "tornado-4.3b1";
    src = fetchurl {
      url = "https://pypi.python.org/packages/source/t/tornado/tornado-4.3b1.tar.gz";
      sha256 = "c7ddda61d9469c5745f3ac00e480ede0703dd1a4ef540a3d9bd5e03e9796e430";
    };
  };
  _aioamqp = with python35Packages; buildPythonPackage {
    name = "aioamqp-0.4.0";
    src = fetchurl {
      url = "https://pypi.python.org/packages/source/a/aioamqp/aioamqp-0.4.0.tar.gz";
      sha256 = "4882ca561f1aa88beba3398c8021e7918605c371f4c0019b66c12321edda10bf";
    };
  };
};
in with dependencies;
stdenv.mkDerivation rec {
  name = "env";
  env = buildEnv { name = name; paths = buildInputs; };
  builder = builtins.toFile "builder.pl" ''
    source $stdenv/setup; ln -s $env $out
  '';
  buildInputs = [
    _rabbitmq_server
    (python35.buildEnv.override {
      ignoreCollisions = true;
      extraLibs = [
        _tornado
        _aioamqp
      ];
    })
  ];
  shellHook = ''
    mkdir -p $PWD/var
    export RABBITMQ_LOG_BASE=$PWD/var
    export RABBITMQ_MNESIA_BASE=$PWD/var
    export RABBITMQ_ENABLED_PLUGINS_FILE=${_enabled_plugins}
    export SSL_CERT_FILE=${cacert}/etc/ssl/certs/ca-bundle.crt
    export PYTHONPATH=`pwd`
  '';
}

The most interesting part is the shellHook (for the nix-shell command) at the end, which configures RabbitMQ server to be run so that its state is stored under the current project directory (./var). Also note, how builtins.toFile nix command is used to create a project specific configuration file for RabbitMQ, to be stored in Nix-store (to not bloat the project directory and to be purged with Nix garbage collector). Any app supporting configuration using environment variables could have a development environment specific configuration in the same way.

To test this out, simply start a few terminals to start RabbitMQ, server and workers (as many as you'd like to):

$ nix-shell --run "rabbitmq-server"
$ nix-shell --run "python3 server.py"
$ nix-shell --run "python3 worker.py"
$ nix-shell --run "python3 worker.py"
$ nix-shell --run "python3 worker.py"

Then then watch requests getting nicely balanced between all the workers:

$ ab -n 1000 -c 100 http://localhost:8080/

You can also follow requests through RabbitMQ's management view at http://localhost:15672 (user: guest, password: guest).

If you'd like to develop the project with IDE, just persist the environment with:

$ nix-build

And point your IDE (e.g. PyCharm) to use the Python interpreter created into ./result/bin/python3.

As an extra, there's an alternative environment with pre-configured supervisord:

$ nix-shell supervisord.nix
[nix-shell]$ supervisord
[nix-shell]$ supervisorctl status
rabbitmq                         RUNNING   pid 17683, uptime 0:00:01
server                           RUNNING   pid 17684, uptime 0:00:01
worker:worker-0                  RUNNING   pid 17682, uptime 0:00:01
worker:worker-1                  RUNNING   pid 17681, uptime 0:00:01
[nix-shell]$ supervisorctl shutdown
Shut down
[nix-shell]$ exit

More information

Nix manual, https://nixos.org/nix/
The official generic Nix manual for installing Nix, learning its built-in commands and the Nix language
Nixpkgs manual, https://nixos.org/nixpkgs/
The Nixpkgs manual for learning conventions and utilities provided in the Nix package collection (Nixpkgs)
Nix planet, http://planet.nixos.org/
Planet for Nix community bloggers
Nixpills, http://lethalman.blogspot.fi/search/label/nixpills
Famous blog series for learning how Nix really works in depth
Nix Conf, http://conf.nixos.org/
The first Nix conference site, hopefully hosting slides and links to recordings after the conference...
#nixos
The Nix, Nixpkgs and NixOS community IRC channel at Freenode
##nix-darwin
The Nix Darwin (OS X) user community IRC channel at Freenode

Generating Plone theming mockups with Chameleon

Some days ago there was a question at the Plone IRC-channel, whether the Plone theming tool supports template inheritance [sic]. The answer is no, but let's play a bit with the problem.

The prefered theming solution for Plone, plone.app.theming, is based on Diazo theming engine, which allows to make a Plone theme from any static HTML mockup. To simplify a bit, just get a static HTML design, write a set of Diazo transformation rules, and you'll have a new Plone theme.

The ideal behind this theming solution is to make the theming story for Plone the easiest in the CMS industry: Just buy a static HTML design and you could use it as a theme as such. (Of course, the complexity of the required Diazo transformation rules depends on the complexity of the theme and themed content.)

But back to the original problem: Diazo encourages the themer to use a plenty of different HTML mockups to keep the transformation rules simple. One should not try to generate theme elements for different page types in Diazo transformation rules, but use dedicated HTML mockups for different page types. But what if the original HTML design came only with a very few selected mockups, and creating the rest from those is up to you. You could either copy and paste, or...

Here comes a proof of concept script for generating HTML mockups from TAL using Chameleon template compiler (and Nix to remove need for virtualenv, because of Python dependencies).

But at first, why TAL? Because METAL macros of TAL can be used to make the existing static HTML mockups into re-usable macros/mixins with customizable slots with minimal effort.

For example, an existing HTML mockup:

<html>
<head>...</head>
<body>
...
<div>
Here be dragons.
</div>
...
</body>
<html>

Could be made into a re-usable TAL template (main_template.html) with:

<metal:master define-macro="master">
<html>
<head>...</head>
<body>
...
<div metal:define-slot="content">
Here be dragons.
</div>
...
</body>
<html>
</metal:master>

And re-used in a new mockup with:

<html metal:use-macro="main_template.macros.master">
<body>
<div metal:fill-slot="content">
Thunderbirds are go!
</div>
</body>
<html>

Resulting a new compiled mockup:

<html>
<head>...</head>
<body>
...
<div>
Thunderbirds are go!
</div>
...
</body>

The script maps all direct sub-directories and files with .html suffix in the same directory with the compiled template into its TAL namespace, so that macros from those can be reached with METAL syntax metal:use-macro="filebasename.macros.macroname" or metal:use-macro="templatedirname['filebasename'].macros.macroname".

Finally, here comes the example code:

#! /usr/bin/env nix-shell
#! nix-shell -i python -p pythonPackages.chameleon pythonPackages.docopt pythonPackages.watchdog
"""Chameleon Composer

Copyright (c) 2015 Asko Soukka <asko.soukka@iki.fi>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Usage:
  ./compose.py <filename>
  ./compose.py src/front-page.html
  ./compose.py <source> <destination> [--watch]
  ./compose.py src build
  ./compose.py src build --watch

"""
from __future__ import print_function
from chameleon import PageTemplateFile
from chameleon import PageTemplateLoader
from docopt import docopt
from watchdog.observers import Observer
from watchdog.observers.polling import PollingObserver
from watchdog.utils import platform
import os
import sys
import time


def render(template):
    assert os.path.isfile(template)

    # Add siblings as templates into compilation context for macro-use
    context = {}
    dirname = os.path.dirname(template)
    for name in os.listdir(dirname):
        path = os.path.join(dirname, name)
        basename, suffix = os.path.splitext(name)
        if os.path.isdir(path):
            context[basename] = PageTemplateLoader(path, '.html')
        elif suffix == '.html':
            context[basename] = PageTemplateFile(path)

    return PageTemplateFile(template)(**context).strip()


class Composer(object):
    def __init__(self, source, destination):
        self.source = source
        self.destination = destination
        self.mapping = {}
        self.update()

    def update(self):
        source = self.source
        destination = self.destination
        mapping = {}

        # File to file
        if os.path.isfile(source) and os.path.splitext(destination)[-1]:
            mapping[source] = destination

        # File to directory
        elif os.path.isfile(source) and not os.path.splitext(destination)[-1]:
            mapping[source] = os.path.join(
                destination,
                os.path.splitext(os.path.basename(source))[0] + '.html'
            )

        # Directory to directory
        elif os.path.isdir(source):
            for filename in os.listdir(source):
                path = os.path.join(source, filename)
                if os.path.splitext(path)[-1] != '.html':
                    continue
                mapping[path] = os.path.join(
                    destination,
                    os.path.splitext(os.path.basename(path))[0] + '.html'
                )

        self.mapping = mapping

    def __call__(self):
        for source, destination in self.mapping.items():
            if os.path.dirname(destination):
                if not os.path.isdir(os.path.dirname(destination)):
                    os.makedirs(os.path.dirname(destination))
            with open(destination, 'w') as output:
                print('{0:s} => {1:s}'.format(source, destination))
                output.write(render(source).strip().encode('utf-8'))

    # noinspection PyUnusedLocal
    def dispatch(self, event):
        # TODO: Build only changed files
        self.update()
        self.__call__()

    def watch(self):
        if platform.is_darwin():
            observer = PollingObserver()  # Seen FSEventsObserver to segfault
        else:
            observer = Observer()
        observer.schedule(self, self.source, recursive=True)
        observer.start()
        try:
            while True:
                time.sleep(1)
        except KeyboardInterrupt:
            observer.stop()
        observer.join()
        sys.exit(0)


if __name__ == '__main__':
    arguments = docopt(__doc__, version='Chameleon Composer 1.0')

    if arguments.get('<filename>'):
        print(render(arguments.get('<filename>')))
        sys.exit(0)

    composer = Composer(arguments.get('<source>'),
                        arguments.get('<destination>'))
    composer()

    if arguments.get('--watch'):
        print('Watching {0:s}'.format(arguments.get('<source>')))
        composer.watch()