Crane

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
`image`	string	If not given, the service name will be used
`build`	object	Maps to `docker build`. Keys: `context` (string) `file/dockerfile` (string) `build-arg/args` (array/map)
`requires`/`depends_on`	array	Container dependencies
`add-host`/`extra_hosts`	array
`blkio-weight`	integer
`blkio-weight-device`	array
`cap-add`/`cap_add`	array
`cap-drop`/`cap_drop`	array
`cgroup-parent`/`cgroup_parent`	string
`cidfile`	string
`cpu-period`	integer
`cpu-quota`	integer
`cpuset`	integer
`cpu-shares`	integer
`detach`	boolean
`detach-keys`	string
`devices`/`device`	array
`device-read-bps`	array
`device-read-iops`	array
`device-write-bp`	array
`device-write-iops`	array
`dns`	array
`dns-opt`	array
`dns-search`/`dns_search`	array
`entrypoint`	string
`env`/`environment`	array/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_file`	array
`expose`	array
`external_links`	array	Link to container started outside of Crane.
`group-add`/`group_add`	array
`health-cmd` `healthcheck>test`	string	Array form of docker-compose is not (yet) supported.
`health-interval` `healthcheck>interval`	string
`health-retries` `healthcheck>retries`	integer
`health-timeouts` `healthcheck>timeout`	string
`hostname`	string
`init`	boolean
`interactive`/`stdin_open`	boolean
`ip`	string
`ip6`	string
`ipc`	string	The `container:id` syntax is not supported, use `container:name` if you want to reuse another container IPC.
`isolation`	string
`kernel-memory`	string
`label`/`labels`	array/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-file`	array
`link`/`links`	array	Doubles as a dependency when used without a custom network.
`log-driver`	string	Use `logging` for docker-compose.
`log-opt`	array	Use `logging` for docker-compose.
`lxc-conf`	array
`mac-address`/`mac_address`	string
`memory`	string
`memory-reservation`	string
`memory-swap`	string
`memory-swappiness`	integer
`net`/`network_mode`	string	The `container:id` syntax is not supported, use `container:name` if you want to reuse another container network stack.
`net-alias`	array
`networks`	array/map	If a map is used, each network can be configured with additional options: `alias`/`aliases`, `ip`/`ipv4_address` and `ip6`/`ipv6_address`.
`oom-kill-disable`	boolean
`oom-score-adj`	string
`pid`	string
`privileged`	boolean
`publish`/`ports`	array
`publish-all`	boolean
`read-only`/`read_only`	boolean
`restart`	string
`rm`	boolean
`runtime`	string
`security-opt`/`security_opt`	array
`share-ssh-socket`	boolean	Adds `--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_size`	string
`sig-proxy`	boolean	`true` by default
`stop-signal`/`stop_signal`	string
`tmpfs`	array
`tty`	boolean
`ulimit`	array
`user`	string
`uts`	string
`volume`/`volumes`	array	In contrast to plain Docker, the host path can be relative.
`volume-driver`/`volume_driver`	string
`volumes-from`	array
`workdir`/`working_dir`	string
`cmd`/`command`	array/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:

Crane automatically creates a default network for you, and all containers connect to it using their name as an alias. Therefore, containers can reach each other by name.

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.