Crane is a Docker orchestration tool similar to Docker Compose
with extra features and ultra-fast bind-mounts on Mac.

Configuration

The configuration defines a map of services in either JSON or YAML. Crane can read from multiple configuration files and merge them. By default it reads (in this order, last one wins) docker-compose.yml, docker-compose.override.yml, crane.yml and crane.override.yml. This can be overwritten by passing --config (multiple times if desired) or setting CRANE_CONFIG (use colons to specify multiple files). If the given paths are relative, Crane searches for the configuration in the current directory, then recursively in the parent directory.

An example config looks like this:

services:
  cranedev:
    image: michaelsauter/golang:1.7
    rm: true
    interactive: true
    tty: true
    volume: ["$GOPATH:/go"]
    workdir: /go/src/github.com/michaelsauter/crane
    command: ["sh"]

The configuration knows the following top-level keys:

Services

The map of services consists of the name of the container mapped to the container configuration, which is made up of the following keys. You may specify either the "Compose key" or the "Crane key", both have the same effect.

Crane / Compose key Type Notes
imagestringIf not given, the service name will be used
buildobjectMaps to docker build. Keys:
  • context (string)
  • file/dockerfile (string)
  • build-arg/args (array/map)
requires/depends_onarray Container dependencies
add-host/extra_hostsarray
blkio-weightinteger
blkio-weight-devicearray
cap-add/cap_addarray
cap-drop/cap_droparray
cgroup-parent/cgroup_parentstring
cidfilestring
cpu-periodinteger
cpu-quotainteger
cpusetinteger
cpu-sharesinteger
detach boolean
detach-keysstring
devices/devicearray
device-read-bpsarray
device-read-iopsarray
device-write-bparray
device-write-iopsarray
dnsarray
dns-optarray
dns-search/dns_searcharray
entrypointstring
env/environmentarray/map Can be declared as a string array with "key[=value]" items or a string-to-string mapping where each key: value will be translated to the corresponding "key=value" string.
env-file/env_filearray
exposearray
group-add/group_addarray
health-cmd
healthcheck>test
stringArray form of docker-compose is not (yet) supported.
health-interval
healthcheck>interval
string
health-retries
healthcheck>retries
integer
health-timeouts
healthcheck>timeout
string
hostnamestring
init boolean
interactive/stdin_open boolean
ipstring
ip6string
ipcstring The container:id syntax is not supported, use container:name if you want to reuse another container IPC.
isolationstring
kernel-memorystring
label/labelsarray/map Can be declared as a string array with "key[=value]" items or a string-to-string mapping where each key: value will be translated to the corresponding "key=value" string.
label-filearray
link/linksarrayDoubles as a dependency when used without a custom network.
log-driverstringUse logging for docker-compose.
log-optarrayUse logging for docker-compose.
lxc-confarray
mac-address/mac_addressstring
memorystring
memory-reservationstring
memory-swapstring
memory-swappinessinteger
net/network_modestringThe container:id syntax is not supported, use container:name if you want to reuse another container network stack.
net-aliasarray
networksarray/mapIf a map is used, each network can be configured with additional options: alias/aliases, ip/ipv4_address and ip6/ipv6_address.
oom-kill-disableboolean
oom-score-adjstring
pidstring
privilegedboolean
publish/portsarray
publish-allboolean
read-only/read_onlyboolean
restartstring
rmboolean
security-opt/security_optarray
share-ssh-socketbooleanAdds --volume $SSH_AUTH_SOCK:/ssh-socket and --env SSH_AUTH_SOCK=/ssh-socket, which forwards the hosts' SSH agent into the container
shm-size/shm_sizestring
sig-proxyboolean true by default
stop-signal/stop_signalstring
tmpfsarray
ttyboolean
ulimitarray
userstring
utsstring
volume/volumesarray In contrast to plain Docker, the host path can be relative.
volume-driver/volume_driverstring
volumes-fromarray
workdir/working_dirstring
cmd/commandarray/string Command to append to docker run (overwriting CMD).

See the Docker documentation for more details about the parameters.

Networks

Docker networks are supported via the top-level config networks. Networks are automatically created by Crane when necessary, and never cleaned up. When a prefix is used, it is also applied to the network.

Containers may have dependencies that should be started prior to themselves. Once configured via requires/depends_on, Crane will take care of start order etc.

services:
  foo:
    requires: ["bar"]
    networks:
      qux:
  bar:
    networks:
      qux:
        alias: ["baz"]
networks:
  qux:

Volumes

Docker volumes are supported via the top-level config volumes. Volumes are automatically created by Crane when necessary, and never cleaned up. When a prefix is used, it is also applied to the volume.

services:
  foo:
    volume: ["bar:/path"]
volumes:
  bar:

Groups

Next to services, you can also specify groups, and then execute Crane commands against those groups. If you do not specify any target, the command will apply to all services. However, you can override this by specifying a default group. Groups of services can be specified like this (YAML shown):

services:
  database1:
    ../..
  database2:
    ../..
  service1:
    ../..
  service2:
    ../..
groups:
  default: ["service1", "database1"]
  databases: ["database1", "database2"]
  services: ["service1", "service2"]

This could be used like so: crane provision service1, crane run databases or crane up services. crane status is an alias for crane status default in this example. If default were not specified, then crane up would start database1, database2, service1 and service2.

Copyright © 2018 Michael Sauter — Contact