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.

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

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

  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.

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


  pause [<target>]
    Pause running containers.


  unpause [<target>]
    Unpause paused containers.


  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.

  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.


  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.


  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.

  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.


Customizing 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 commands

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.

Copyright © 2018 Michael Sauter — Contact