What is this?
dork-compose is a drop in replacement for the docker-compose command line
tool, adding some convenience features for running multiple compose projects on
the same host.
- Volume snapshots with automatic versioning.
- Separation of Docker setup (
application source code.
- Automatic launch of and connection to auxiliary services, like
nginx or a DNS server.
Example use cases:
- Your local development workstation, hosting multiple different projects built
on the same framework, and therefore requiring similar infrastructure and
- A staging server running multiple versions of the same project, doing fast
upgrade testing by using volume snapshots.
- A continuous integration server, running automatic tests on pull requests.
dork-compose uses the same installation procedures as docker-compose.
Either using pip:
pip install dork-compose
dork-compose does additionally to
docker-compose is implemented
using plugins. The
DORK_PLUGINS environment variable controls which plugins
are loaded and in which order they are executed. Plugins are able to alter
environment variables, modify the configuration from
act on certain events throughout the
docker-compose command processes.
By default the
DORK_PLUGINS variable looks like this:
That's the default workstation setup. Plugins are executed from left to right.
If two plugins to the same, the right one wins.
Let's run through this example:
env: Scans parent directories for
populates the environment with their contents.
multi: Run multiple different projects on the same host. The
project name will be the name ofthe containing directory. It is used
to prefix snapshots and build the domain.
lib: If there is a
DORK_LIBRARYenvironment variable that contains a
dork-composewill assume the
dork-composewill take care of handling the container build process
autbuild: Automatically build docker images of application
sources if using onbuild images.
hotcode: Mount code directories you work on into your local codebase and provide vendor code to your IDE.
filesystem: Implements snapshots as plain rsync. Not particularly fast or
disk space economic, but works out of the box everywhere.
proxy: Spins up a proxy service that serves your project at
dns: Runs a dns server and configures your system to use it. Enables you
to use the domain
vault: Exposes secrets (e.g. the github private token) to the build
process without leaving any traces in the image.
There are no configuration files. Plugins can be configured using environment
variables, which you define in your shell environment for by using the env
plugin. For a complete list of plugins and their options please refer to
Appendix: Plugins. For an in-action example of these plugins, please refer
to the drupal-simple
in the recipes repository.
It's possible to create and load custom plugins. Simply create a Python file
with one class called Plugin that extends
attach it to the
For example plugins have a look at the
plugins directory inside the
dork-compose is able to create snapshots of all data volumes used in a compose
project. This is done by using the additional
dork-compose snapshot command.
For an example of how to work with snapshots, please refer to the
drupal-simple example in the recipes repository.
Projects & Instances
Snapshots are organized in projects and instances.
that instances of the same project are compatible. Aside from building the proxy
domain, the major purpose is to restrict snapshots to be used by instances of
the same project only.
The current project and instance is determined by plugins (like multi in
the default setup) or by the
If the snapshot identifier is omitted from the
snapshot save and
snapshot load command,
dork-compose will rely on plugins to provide one.
The git plugin in the default setup for example will store snapshots by the
current HEAD hash and will try to load the closest available ancestor to the
current checkout. This avoids breaking your development database by switching
between feature branches.
TODO: explain all builtin plugins.