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

Command Line Interface

Crane is a very light wrapper around the Docker CLI. This means that most commands just call the corresponding Docker command, but for all targeted services. The basic format is crane <command> <target>, where <command> corresponds to a Docker command, and <target> either is a single container or a group.

When executing commands, keep the following 2 rules in mind:

  1. Crane will apply the command ONLY to the target
  2. Crane will do with other services in the configuration whatever it takes in order for (1) to succeed

As an example, imagine you have a container web depending on container database. When you execute crane run web, then Crane will start database first, then run web (recreating web if it already exists).

usage: crane [<flags>] <command> [<args> ...]

Lift containers with ease - https://www.craneup.tech

Flags:
      --help                    Show context-sensitive help (also try
                                --help-long and --help-man).
  -v, --verbose                 Enable verbose output.
      --dry-run                 Dry run (implicitly verbose; no side effects).
  -c, --config=~/crane.yml ...  Location of config file(s).
  -p, --prefix=PREFIX           Container/Network/Volume prefix.
  -x, --exclude=container|group ...  
                                Exclude group or container (repeatable).
  -o, --only=container|group    Limit scope to group or container.
  -e, --extend                  Extend command from target to dependencies.
      --tag=TAG                 Override image tags.

Commands:
  help [<command>...]
    Show help.


  up [<flags>] [<target>] [<cmd>...]
    Build or pull images if they don't exist, then run or start the containers.
    Alias of `lift`.

    -n, --no-cache    Build the image(s) without any cache.
    -l, --parallel=1  Define how many containers are provisioned in parallel.
    -d, --detach      Detach from targeted container.

  lift [<flags>] [<target>] [<cmd>...]
    Build or pull images if they don't exist, then run or start the containers.
    Alias of `up`.

    -n, --no-cache    Build the image(s) without any cache.
    -l, --parallel=1  Define how many containers are provisioned in parallel.
    -d, --detach      Detach from targeted container.

  run [<flags>] [<target>] [<cmd>...]
    Run containers. Already existing containers will be removed first.

    -d, --detach  Detach from container.

  create [<target>] [<cmd>...]
    Create containers. Already existing containers will be removed first.


  start [<target>]
    Start stopped containers. Non-existant containers will be created.


  stop [<target>]
    Stop running containers.


  kill [<target>]
    Kill running containers.


  exec [<flags>] [<target>] [<cmd>...]
    Execute command in the targeted container(s). Stopped containers will be
    started, non-existant containers will be created first.

    --privileged  Give extended privileges to the process.
    --user=USER   Run the command as this user.

  rm [<flags>] [<target>]
    Remove stopped containers.

    -f, --force    Remove running containers, too.
        --volumes  Remove volumes as well.

  pause [<target>]
    Pause running containers.


  unpause [<target>]
    Unpause paused containers.


  provision [<flags>] [<target>]
    Build or pull images.

    -n, --no-cache    Build the image(s) without any cache.
    -l, --parallel=1  Define how many containers are provisioned in parallel.

  pull [<target>]
    Pull images.


  push [<target>]
    Push containers to the registry.


  logs [<flags>] [<target>]
    Show container logs.

    -f, --follow       Follow log output.
        --tail=TAIL    Define number of lines to display at the end of the logs.
    -t, --timestamps   Show timestamps.
    -z, --colorize     Use different color for each container.
        --since=SINCE  Show logs since timestamp.

  stats [<flags>] [<target>]
    Display statistics about containers.

    -n, --no-stream  Disable stats streaming.

  status [<flags>] [<target>]
    Display status of containers (similar to `docker ps`).

    -n, --no-trunc  Don't truncate output.

  cmd [<command>] [<arguments>...]
    Execute predefined shortcut command.


  generate [<flags>] [<target>]
    Generate files by passing the config to given template.

    -t, --template=TEMPLATE  Template to use.
    -O, --output=OUTPUT      The file(s) to write the output to.

  am reset [<target>]
    Reset accelerated mount.


  am logs [<flags>] [<target>]
    Show logs of accelerated mount.

    -f, --follow  Follow log output.

  version [<flags>]
    Display the current version and check for updates.

    -n, --no-check  Don't check for updates.


Adjusting targets

By default, Crane will apply the command ONLY to the target. For example, if you have a container web that depends on a container db, then executing crane run web will make sure that db is started before running web (recreating it if it already exists). If you want to extend the target - in this example to recreate db as well if it already exists - you can use --extend

If you want to exclude a container or a whole group from a Crane command, you can specify this with --exclude <reference> (or via CRANE_EXCLUDE). The flag can be repeated to exclude several services or groups (use a multi-line environment variable value to pass several references via CRANE_EXCLUDE). Excluded services' declaration and references in the configuration file will be completely ignored, so their dependencies will also be excluded (unless they are also required by other non-excluded services).

Apart from excluding services, it is also possible to limit the target to just one container or group with --only (or via CRANE_ONLY). The flag cannot be repeated. Containers outside the targets will not be considered by Crane then.

Ad hoc containers

If you append a command to up/lift or run, Crane will add a timestamp to the container name (e.g. foo will become foo-1447155694523), making it possible to have multiple containers based on the same Crane config.

Custom commands

Often you'll want to execute the same command inside a container over and over again. Crane allows to define shortcuts for them in the configuration, which can be executed via crane cmd. For example, you can define console: run web bin/rails c inside the commands section of the configuration to run an ad-hoc web container with the rails c command inside by simply executing crane cmd console from the host. This is effectively the same as running the longer crane run web bin/rails c.

The shortcuts can be defined as strings or arrays, and may start with any valid Crane subcommand. That means you can use them to run containers, or execute commands inside existing containers etc. The CLI interface accepts further arguments, which are simply appended to the predefined command. It is possible to list available commands by typing just crane cmd. Some examples:

commands:
  console: run web bin/rails c
  server: run web
  rspec: run web bin/rspec
  rubocop: run web bin/rubocop
  psql: exec postgres psql

Usage is simple: crane cmd console would start a Rails console in the default (development) environment, and using crane cmd console test would append test to the predefined command, starting a console in the test environment.

Copyright © 2018 Michael Sauter — Contact