docker-init-script
Build/generate and install an init script for your docker containers making them run as services on Debian/Ubuntu based systems. This will quickly and easily generate a generic docker init script capable of forwarding all docker commands to the docker instance and include support for start, stop, restart so that Debian based systems will be able to safely start and shutdown the instances at the appropriate run level when enabled.
Basic Usage
git clone git@github.com:flungo/docker-init-script.git
cd docker-init-script
make enable SERVICE=service-name DESCRIPTION="A description of your service (this is optional)"
The values for SERVICE and DESCRIPTION should be filled out when running the script with the appropriate details (see Variables below for more information).
This git can also be included as a submodule within your package and call the make file as appropriate from either a bash script or another make file. This makes it easy to build a fully distributable package for your application that not only includes the Dockerfile and everything else required to build the container but that you can provide easy but customisable methods of implementing (see tutorial).
Advanced usage
To use some of the more advanced features you will probably want to further customise the parameters that make can take.
make <target> [<variable>=<value> ...]
The make script also allows you to provide additional code to the executed on events through the use of Script Hooks.
Variables
- SERVICE - The name of the container and hence the service that will be created. (Default:
docker-service
) - CONTAINER - The name of the container (Default: The same as the value of SERVICE)
- DESCRIPTION - A description of the service (only used in the header of the generated init script) (Default: "A service to provide interface to the docker container ")
- TEMPLATE - The location of the template to use if you wish to use an alternative template to the default one docker-service-init (Default:
docker-service-init
) - SCRIPT_DIR - The folder where scripts can be found. Useful to make the directory a bit more organised or when using as a submodule to link to a folder in the parent directory (e.g.
../scripts
) (Default: ``) - OUTPUTDIR - The location to output the files to including a trailing slash (Default:
build/
)
Targets
- generate - Generates the file to build/
- install - Builds if required and installs the init script to the
/etc/init.d
directory - enable - Installs if required and enables the script to automatically start the service on startup and stop it on shutdown
- disable - Disables the script from starting at boot time and being stopped when shutdown
- uninstall - Removes the init script from the
/etc/init.d
directory - clean - Removed the
build
directory and all the files within it - scripts - Generates dummy scripts for all hook scripts.
Script Hooks
Hook scripts allow you to build persistent environments on the host system. Some great uses for this functionality would be when using [pipework][https://github.com/jpetazzo/pipework] or when you might need to do some cleanup. With hook scripts you can specify a set of commands for certain events: for example, with pipework I would use a POST_START script to setup the networking. This makes your configurations for the host persistent and consistent.
Currently there are 10 script hooks available as listed below:
- PRE_START - Executed before the container is started.
- POST_START - Executed after the container is started.
- PRE_STOP - Executed before the container is stopped.
- POST_STOP - Executed after the container is stopped.
- PRE_RESTART - Executed before the container is restarted.
- POST_RESTART - Executed after the container is restarted.
- PRE_PAUSE - Executed before the container is paused.
- POST_PAUSE - Executed after the container is paused.
- PRE_UNPAUSE - Executed before the container is unpaused.
- POST_UNPAUSE - Executed after the container is unpaused.
The hooks provided are more than I could even think of uses for but if there is a hook for another command that would be useful, please suggest it in the issues section with an explanation of what you would like to achieve.
Creating hooks
To use a script hook, simply create a file with the respective hook name in the same directory as the Makefile and then when make
is run, the contents of the file will be inserted into the init file template at the appropriate point. There have also been some convenience targets added to the Makefile meaning to quickly generate a stub file for a PRE_START event you can execute make PRE_START
. As well as a target for each event, there are also some grouped targets that will create a batch of files:
- START_SCRIPTS - Generates both a
PRE_START
andPOST_START
script file. - STOP_SCRIPTS - Generates both a
PRE_STOP
andPOST_STOP
script file. - RESTART_SCRIPTS - Generates both a
PRE_RESTART
andPOST_RESTART
script file. - PAUSE_SCRIPTS - Generates both a
PRE_PAUSE
andPOST_PAUSE
script file. - UNPAUSE_SCRIPTS - Generates both a
PRE_UNPAUSE
andPOST_UNPAUSE
script file. - scripts - Generates all hook scripts.
Scripting
All script files are expected to be in bash syntax as well as being fully self-contained. If you wish to use external files please not that the Makefile does not handle importing and making your dependencies available. It may be usefull to look into bash heredocs which can allow scripts of languages other than bash to be included in your script.
Additionally you can use variable tags which will be substituted at make time. See Template Tags
Templates
In the event you need to do some really complicated changes to the generated init file or you just don't like the template provided, then this can be edited. This file is currently in the format of a bash init file but I suppose there is nothing stopping you from writing yours in perl, python or even [Brainfuck][http://en.wikipedia.org/wiki/Brainfuck] but bash was chosen as those languages require an interpreter that may not be included as standard on some minimal debian images. Most modern images use BASH so this seemed like a safe choice.
Template Tags
If you do write your own template then it would be good to know about the template tags used. At the moment the tags are limited to:
- - Replaced with the value of
DESCRIPTION
as defined in the make command. - - Replaced with the value of
SERVICE
as defined in the Makefile. - - Replaced with the value of
CONTAINER
as defined in the Makefile.
The substitutions are made in the order provided so if a contains a tag, it will be replaced.
Template Script Hooks
Script hooks are implemented by adding the contents of the script file after the line containing a match for ### BEGIN PRE_START_SCRIPT ###
(in the situation of marking where the PRE_START
script should be inserted). For clarity of reading after generation, I have implemented the tags as shown below but the END tag is not required.
### BEGIN PRE_START_SCRIPT ###
### END PRE_START_SCRIPT ###
Tutorial
A tutorial of usage will be added here showing as many features as possible with an example project (which will also be available as a separate repository.)
Contributing
Found a problem? Want a feature? Submit an issue in the issue tracker and I will see if it can be done. Pull requests are welcomed if you are able to make the modifications you would like to see yourself but please try to maintain the structure and organisation of the code you write.