Dockron is able to execute docker commands on (groups of) entities on a regular
basis, based on a cron-like syntax. Example of such entities are containers,
but also, networks, (Swarm) nodes, secrets, etc. It relies on the Docker client
implementation in Tcl (See the end of this document for how to resolve
The rationale for Dockron is to be able to move scheduling (as in time
scheduling, not container scheduling) into one or several central places.
Sometimes, you need to schedule tasks that are meaningful to your
application/stack, and expressing these as a Dockron service (in a compose file,
for example) is meaningful. Other scenarios are to regularily schedule various
operations on an entire Swarm.
Dockron is able to connect to the local Docker UNIX socket, but also remote
docker daemons. The program takes a number of dash-led options and arguments.
Provided it is properly installed, running it as below should provide help for
The actions to perform on entities are taken from the command-line option
-rules. Its value should be a white-space separated list of specifications,
which needs to contain a multiple of 8 items. The items are taken in turns and
are interpreted as described below:
- The minute of the day (see below)
- The hour of the day (see below)
- The day of the month (see below)
- The month number (see below)
- The day of the week (see below)
- The combination of an entity type and a glob-style pattern to match against
the name(s) of the entity. When the type is not explicitely specified, it
will be considered to target containers.
- The command to execute, e.g.
pause, as available from the
- Additional arguments to the command.
For all the date and time related specifications, the component controller
crontab conventions, meaning that you should be able to specify
*, but also intervals such as
0-5,14-18,34, or "every 3" using
*/3. The command to execute can be empty, in which case the arguments are
used in a slightly different way as explained below.
Matching Types and Entities
When looking for matching entities, the specification (6th argument in the rule
list) should be composed of a type specification, followed by a slash
followed by a glob-style pattern. The type can be omitted, in which case the
slash can also be omitted. Empty patterns lead to slightly different behaviours
The type specification is case insensitive and can be shortened to the minimum
descriptive string within the set of entities for brievity. At present, Dockron
supports the following (mostly self explanatory) types of entities:
Cor any string beginning with
CONT(as for example
Sor any string beginning with
SER(as for example
SERVICE). This will
match against the existing services among a manager of the swarm.
- Any string beginning with
V(as for example
- Any string beginning with
I(as for example
Nor any string beginning with
NO(as for example
NODE). This will
match against the existing nodes known to a manager of the swarm.
Wor any string beginning with
NE(as for example
Ror any string beginning with
SEC(as for example
SECRET). This will
match against the existing secrets known to a manager of the swarm.
Gor any string beginning with
CONF(as for example
CONFIG). This will
match against the existing configurations known to a manager of the swarm.
In general, the glob-style pattern will be matched against the name(s) of the
entities. For containers, the leading slashes of the name will not be
considered. For images, matching will happen against the tags.
Command Construction and Execution
When constructing the API call to communicate with the Docker daemon, the
identifiers of all the entities matching the pattern will automatically be
appended to the command, followed by the arguments. For example, a rule
specification expressed as follows will arrange for restarting all containers
matching the pattern
12 */2 * * * C/*myworker* "container restart" ""
Empty Patterns for System Commands
An empty glob-style pattern (or the single dash
-) is a special case that can
be used for system commands, or commands that do not operate on a specific
prune commands. For example, a rule expressed as follows will
arrange to prune all stopped containers at a host.
12 */2 * * * C/- "container prune" ""
Empty Commands for Complex Commands
An empty command is yet another special case, a case that can be used to express
more complex command sequences. In that case, the remaining arguments are used
to form a Tcl command that will communicate with the Docker daemon once some
keywords have been substituted. Keywords are surrounded by the percent
sign, and the list of known keywords is the following:
%docker%, an alias) will automatically be replaced by the internal
identifier of the Docker connection, as returned by calls to
by the API implementation.
%id%will be replaced by the identifier of the entity that matched the
%name%will be replaced by the name of the entity that matched the pattern.
For example, a rule specification as below will, once again, but expressed
differently restart all containers matching the pattern
*myworker*. Note the
use of the leading
%cx%, and of
%id% which will, once dynamically
substituted, lead to a valid call to the Tcl Docker API implementation.
12 */2 * * * C/*myworker* "" "%cx% container restart %id%"
Note that the command formed as such is called directly in the context of the
executing procedure and there are no security guards, nor execution within a
When the first character of the arguments is an arobas
@, all characters after
the arobas form the path to a template file that will be read once. Its content
will be substituted each time necessary, as if it had come from the arguments
and is explained in the previous section. Offloading content to a file allows
for even more complex calls and/or construction, benefiting from the entire
expressiveness of the Tcl syntax.
For example, creating the following content in a file called
arranging for setting the 8th item of the rule list to
arrange to prune away all dangling images. Note that the command makes a direct
docker filters, a helper procedure from the Docker Tcl implementation
meant to facilitate the construction of JSON expressions that should be sent as
part of the API query.
%cx% image prune -filter [docker filters dangling 1]
To run Dockron from compose, you would could specify something like the
following, which would automatically restart two sorts of worker components once
every two hours. Pay attention to the quotes around starting and ending the list
watchdog: image: efrecon/dockron restart: always volumes: - /var/run/docker.sock:/var/run/docker.sock:ro command: >- -rules "12 */2 * * * *myworker* restart \"\" 13 */2 * * * *myotherworker* restart \"\"" -verbose INFO
Installation and Dependencies
Dockron is best run as a Docker container. Get it from the hub, where it
will always be available at its latest version, or build it yourself using:
docker build -t efrecon/dockron .
To run it locally, you will need to mount the docker socket into the component,
e.g. (but the following command wouldn't do much...):
docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock efrecon/dockron -h
Directly on the Host
You need to ensure that dockron can access the
docker under-directory of the
engine Tcl implementation. You can either copy the content of the
directory or arrange for a (symbolic) link. Checkout for how the
solves the dependency for an example.