The code for the example is in examples/hello_world_server/.

Building and delivering software is a complex task that can be made easier with proper encapsulation: Containers. They are able to pack all required dependencies (bitwise version controlled) so that you can release code with the confidence that everything works the same way it worked on the developers machine.

The current default for building and packing software into containers is using Dockerfiles¹ offered by the Docker® software. This, however, has several structural disadvantages:

• Build Container is the Deliverable Container
• Only one-dimensional caching of build steps
• No support for slimmed containers
• Unnecessary layers

Involucro [from Latin for 'envelope'] detaches the build process from the deliverable container and re-establishes proper encapsulation in containers: One Process, One Container.

From source:

$ go get github.com/involucro/involucro/cmd/involucro
$ $GOPATH/bin/involucro --version

As binary for Linux: involucro

Or, for Windows: involucro.exe involucro32.exe

And for Mac OSX: involucro.darwin

Involucro is configured by a Lua script file. By default, it is looking for invfile.lua in the current directory, but this can be overridden (see below).

A configuration file contains a set of tasks identified by a unique name. These names can be specified when invoking involucro and are executed in the order they are given. For example, $ involucro build package will run the build and afterwards the package task. A task can be created by invoking inv.task('<ID>') in the configuration file.

For easy readability, the configuration file uses a fluent syntax to build the tasks. The available methods are either modifying the next registered step, or are registering a step. This type distinction is documented below for each method.

inv.task('<ID>') (modifier) sets the task of the next registered step to <ID>. It makes the methods using, runTask, and wrap available.

Each task consists of a list of steps that are run in the order they are given in the file. There are different types of steps. Each step has one introductory method made available from the task, a set of modifying methods setting different properties of the step, and a final registration method that registers these settings for execution. The current status can be stored at any point into a variable and reused later. However, the steps are strictly run in the order their registration method was called.

A run step executes a Docker container. By default, the current working directory is mounted as /source into the container which is also configured to be the working directory of the process running in the container. It is mainly used to transform source code using external processes such as compilers into a different form.

task.using('<IMAGE_ID>') (introductory) starts off a run step by specifying the repository name (optionally with tag) or the image ID of the image to be run. Example: task.using('gcc:4.9').

runstep.withConfig(<TABLE>) (modifying) sets the values in the Lua table as configuration values for the Docker container. The values that can be set here are only affecting the container itself, not how is connected with the host. See withHostConfig for this. The options available are Config. The keys are interpreted case insensitive. Example: runstep.withConfig({Cmd = {"/bin/echo", "Hello, World!"}}).

runstep.withHostConfig(<TABLE>) (modifying) sets the values in the Lua table as host configuration values. These values control the exact execution semantics of the container from the hosts point of view. The available options are documented here: HostConfig. Example: runStep.withConfig({links = {"redis"}}).

NOTE: By default, involucro binds the current directory as /source. If the Binds key is set in the given table it overwrites this binding. Involucro however interprets the given bindings and changes all relative source bindings to absolute paths. This enables bindings such as {binds = {"./dist:/data", "/tmp:/tmp"}}.

runstep.withExpectation(<TABLE) (modifying) registers expectations towards the output and exit code of the process. By default, involucro expects the process to exit cleanly with exit code 0. Tests of executables however may require expecting a process to fail. This can be set with the key code: runstep.withExpectation({code = 1}). Similarly, an expectation towards the output of the process on stdout and/or stderr can be registered with regular expressions conforming to Re2 syntax. Example: runstep.withExpectation({stdout = "Hello, World!\n"}).

runstep.run('<CMD>'...) (registration) registers the run step. The arguments are used as the command-line arguments of the process being run. It directly follows Docker semantics regarding process execution. Each argument is used as a single argument for the process. Example: runstep.run('/bin/echo', 'Hello, World!'). Note that there is no wildcard expansion or variable replacement if the arguments are not given to a shell, such as /bin/sh. Example: runstep.run('/bin/sh', '-c', 'echo *').

A wrap step takes the contents of a directory and creates an image layer out of it, optionally with a parent image layer and meta data. The resulting image can be tagged into a repository with a tag name (or latest, if none is set).

task.wrap('<SOURCE_DIR>') (introductory) starts off a wrap step by specifying the directory containing the files that are to be wrapped into an image. It is also possible to use the current directory (.). Example: task.wrap('dist').

wrapstep.at('<TARGET_DIR>') (modifying) sets the directory in the resulting image into which the files are copied. This can be used to put HTML files into the location the web server in the parent image expects them to be. This directory doesn't need to exist yet. Example: wrapstep.at('/data').

wrapstep.inImage('<PARENT_IMAGE>') (modifying) causes the resulting image to be a child of the image identified by the parameter. If this modification is omitted the resulting image is parent-less. Example: wrapstep.inImage('nginx').

wrapstep.withConfig(<TABLE>) (modifying) sets configuration values similar to the withConfig method of the run step above. This can be used to pre-set an entrypoint or exposed ports. Example: wrapstep.withConfig({exposedports = {"80/tcp"}}).

wrapstep.as('<IMAGE_NAME>') (registration) registers the step for execution. The image constructed by the previous modifications is built and tagged with the given name, which may include a registry designation. Example: wrapstep.as('app:latest')

As a convenience, it is possible to run another task as part of a task. This emulates the conventional all task from Makefiles. Exceptionally, the introductory method for this step is also the registration method.

task.runTask(<ID>) (introductory registration) registers a step that executes the task with the given ID as part of the steps in this task. Example: inv.task('all').runTask('compile').runTask('package').

Sometimes, there should be two versions of the same image sharing the same image ID, for example to have the latest tag equivalent to version v2. The tag step helps in this case.

task.tag(<NAME>) (introductory) starts a tagging by setting the name of the original image. This can be anything Docker accepts, including test/asd:v2, but also actual image IDs. Example: task.tag('test/asd').

tagstep.as(<NAME>) (registration) registers a step that tags the image named in introductory method to the name given as parameter. Example: tagstep.as('test/asd').

Control files can change their behaviour during tasks with hooks, for example to use the results of previous tasks with io.lines.

task.hook(<FUNCTION>) (introductory registration) registers a step that, when taken, runs the given function. No arguments are passed, and any return values are ignored. Example: task.hook(function () print('in step') end).

Tagged images can be pushed to repositories where they can be pulled by other users. This step may involve authentication, see below for details.

**task.push(<NAME>) (introductory registration) registers a step that, when taken, pushes the image with the given name to a remote repository. Note that the default Docker rules apply with regard to names: If a name starts with a server address the image is pushed there, and if not Docker Hub is selected. Example: task.push('image:latest')

Pushes and pulls to a remote registry or to Docker Hub may be neccessary to be authenticated. Involucro solves this by reading a JSON file in the home directory of the current user called .involucro. This file (currently) only contains information about authentication, but more uses may be introduced later.

To configure username, password, and email place a file of the following form into $HOME/.involucro:

{
  "auths": [
    "https://USERNAME:PASSWORD@SERVER.COM/?email=EMAIL@EXAMPLE.COM"
  ]
}

Multiple entries are possible, but only one per server. By definition, the address for Docker Hub is index.docker.io/v1/, so the configuration for a user alice with password b0b and email address alice@devs.io on Docker Hub is:

{
  "auths": [
    "https://alice:b0b@index.docker.io/v1/?email=alice@devs.io"
  ]
}

Please keep this file hidden from any user except you as it contains the password in plaintext!

Docker® is a registered trademark of Docker, Inc.