WIP: rename Fig to Compose

Signed-off-by: Aanand Prasad <aanand.prasad@gmail.com>

compose/__init__.py

@@ -0,0 +1,4 @@
+from __future__ import unicode_literals
+from .service import Service  # noqa:flake8
+
+__version__ = '1.0.1'

compose/cli/colors.py

@@ -0,0 +1,42 @@
+from __future__ import unicode_literals
+NAMES = [
+    'grey',
+    'red',
+    'green',
+    'yellow',
+    'blue',
+    'magenta',
+    'cyan',
+    'white'
+]
+
+
+def get_pairs():
+    for i, name in enumerate(NAMES):
+        yield(name, str(30 + i))
+        yield('intense_' + name, str(30 + i) + ';1')
+
+
+def ansi(code):
+    return '\033[{0}m'.format(code)
+
+
+def ansi_color(code, s):
+    return '{0}{1}{2}'.format(ansi(code), s, ansi(0))
+
+
+def make_color_fn(code):
+    return lambda s: ansi_color(code, s)
+
+
+for (name, code) in get_pairs():
+    globals()[name] = make_color_fn(code)
+
+
+def rainbow():
+    cs = ['cyan', 'yellow', 'green', 'magenta', 'red', 'blue',
+          'intense_cyan', 'intense_yellow', 'intense_green',
+          'intense_magenta', 'intense_red', 'intense_blue']
+
+    for c in cs:
+        yield globals()[c]

compose/cli/command.py

@@ -0,0 +1,122 @@
+from __future__ import unicode_literals
+from __future__ import absolute_import
+from requests.exceptions import ConnectionError, SSLError
+import errno
+import logging
+import os
+import re
+import yaml
+import six
+
+from ..project import Project
+from ..service import ConfigError
+from .docopt_command import DocoptCommand
+from .utils import call_silently, is_mac, is_ubuntu
+from .docker_client import docker_client
+from . import verbose_proxy
+from . import errors
+from .. import __version__
+
+log = logging.getLogger(__name__)
+
+
+class Command(DocoptCommand):
+    base_dir = '.'
+
+    def dispatch(self, *args, **kwargs):
+        try:
+            super(Command, self).dispatch(*args, **kwargs)
+        except SSLError, e:
+            raise errors.UserError('SSL error: %s' % e)
+        except ConnectionError:
+            if call_silently(['which', 'docker']) != 0:
+                if is_mac():
+                    raise errors.DockerNotFoundMac()
+                elif is_ubuntu():
+                    raise errors.DockerNotFoundUbuntu()
+                else:
+                    raise errors.DockerNotFoundGeneric()
+            elif call_silently(['which', 'boot2docker']) == 0:
+                raise errors.ConnectionErrorBoot2Docker()
+            else:
+                raise errors.ConnectionErrorGeneric(self.get_client().base_url)
+
+    def perform_command(self, options, handler, command_options):
+        if options['COMMAND'] == 'help':
+            # Skip looking up the compose file.
+            handler(None, command_options)
+            return
+
+        if 'FIG_FILE' in os.environ:
+            log.warn('The FIG_FILE environment variable is deprecated.')
+            log.warn('Please use COMPOSE_FILE instead.')
+
+        explicit_config_path = options.get('--file') or os.environ.get('COMPOSE_FILE') or os.environ.get('FIG_FILE')
+        project = self.get_project(
+            self.get_config_path(explicit_config_path),
+            project_name=options.get('--project-name'),
+            verbose=options.get('--verbose'))
+
+        handler(project, command_options)
+
+    def get_client(self, verbose=False):
+        client = docker_client()
+        if verbose:
+            version_info = six.iteritems(client.version())
+            log.info("Compose version %s", __version__)
+            log.info("Docker base_url: %s", client.base_url)
+            log.info("Docker version: %s",
+                     ", ".join("%s=%s" % item for item in version_info))
+            return verbose_proxy.VerboseProxy('docker', client)
+        return client
+
+    def get_config(self, config_path):
+        try:
+            with open(config_path, 'r') as fh:
+                return yaml.safe_load(fh)
+        except IOError as e:
+            if e.errno == errno.ENOENT:
+                raise errors.ComposeFileNotFound(os.path.basename(e.filename))
+            raise errors.UserError(six.text_type(e))
+
+    def get_project(self, config_path, project_name=None, verbose=False):
+        try:
+            return Project.from_config(
+                self.get_project_name(config_path, project_name),
+                self.get_config(config_path),
+                self.get_client(verbose=verbose))
+        except ConfigError as e:
+            raise errors.UserError(six.text_type(e))
+
+    def get_project_name(self, config_path, project_name=None):
+        def normalize_name(name):
+            return re.sub(r'[^a-z0-9]', '', name.lower())
+
+        if 'FIG_PROJECT_NAME' in os.environ:
+            log.warn('The FIG_PROJECT_NAME environment variable is deprecated.')
+            log.warn('Please use COMPOSE_PROJECT_NAME instead.')
+
+        project_name = project_name or os.environ.get('COMPOSE_PROJECT_NAME') or os.environ.get('FIG_PROJECT_NAME')
+        if project_name is not None:
+            return normalize_name(project_name)
+
+        project = os.path.basename(os.path.dirname(os.path.abspath(config_path)))
+        if project:
+            return normalize_name(project)
+
+        return 'default'
+
+    def get_config_path(self, file_path=None):
+        if file_path:
+            return os.path.join(self.base_dir, file_path)
+
+        if os.path.exists(os.path.join(self.base_dir, 'compose.yaml')):
+            log.warning("Fig just read the file 'compose.yaml' on startup, rather "
+                        "than 'compose.yml'")
+            log.warning("Please be aware that .yml is the expected extension "
+                        "in most cases, and using .yaml can cause compatibility "
+                        "issues in future")
+
+            return os.path.join(self.base_dir, 'compose.yaml')
+
+        return os.path.join(self.base_dir, 'compose.yml')

compose/cli/docker_client.py

@@ -0,0 +1,35 @@
+from docker import Client
+from docker import tls
+import ssl
+import os
+
+
+def docker_client():
+    """
+    Returns a docker-py client configured using environment variables
+    according to the same logic as the official Docker client.
+    """
+    cert_path = os.environ.get('DOCKER_CERT_PATH', '')
+    if cert_path == '':
+        cert_path = os.path.join(os.environ.get('HOME', ''), '.docker')
+
+    base_url = os.environ.get('DOCKER_HOST')
+    tls_config = None
+
+    if os.environ.get('DOCKER_TLS_VERIFY', '') != '':
+        parts = base_url.split('://', 1)
+        base_url = '%s://%s' % ('https', parts[1])
+
+        client_cert = (os.path.join(cert_path, 'cert.pem'), os.path.join(cert_path, 'key.pem'))
+        ca_cert = os.path.join(cert_path, 'ca.pem')
+
+        tls_config = tls.TLSConfig(
+            ssl_version=ssl.PROTOCOL_TLSv1,
+            verify=True,
+            assert_hostname=False,
+            client_cert=client_cert,
+            ca_cert=ca_cert,
+        )
+
+    timeout = int(os.environ.get('DOCKER_CLIENT_TIMEOUT', 60))
+    return Client(base_url=base_url, tls=tls_config, version='1.14', timeout=timeout)

compose/cli/docopt_command.py

@@ -0,0 +1,54 @@
+from __future__ import unicode_literals
+from __future__ import absolute_import
+import sys
+
+from inspect import getdoc
+from docopt import docopt, DocoptExit
+
+
+def docopt_full_help(docstring, *args, **kwargs):
+    try:
+        return docopt(docstring, *args, **kwargs)
+    except DocoptExit:
+        raise SystemExit(docstring)
+
+
+class DocoptCommand(object):
+    def docopt_options(self):
+        return {'options_first': True}
+
+    def sys_dispatch(self):
+        self.dispatch(sys.argv[1:], None)
+
+    def dispatch(self, argv, global_options):
+        self.perform_command(*self.parse(argv, global_options))
+
+    def perform_command(self, options, handler, command_options):
+        handler(command_options)
+
+    def parse(self, argv, global_options):
+        options = docopt_full_help(getdoc(self), argv, **self.docopt_options())
+        command = options['COMMAND']
+
+        if command is None:
+            raise SystemExit(getdoc(self))
+
+        if not hasattr(self, command):
+            raise NoSuchCommand(command, self)
+
+        handler = getattr(self, command)
+        docstring = getdoc(handler)
+
+        if docstring is None:
+            raise NoSuchCommand(command, self)
+
+        command_options = docopt_full_help(docstring, options['ARGS'], options_first=True)
+        return options, handler, command_options
+
+
+class NoSuchCommand(Exception):
+    def __init__(self, command, supercommand):
+        super(NoSuchCommand, self).__init__("No such command: %s" % command)
+
+        self.command = command
+        self.supercommand = supercommand

compose/cli/errors.py

@@ -0,0 +1,62 @@
+from __future__ import absolute_import
+from textwrap import dedent
+
+
+class UserError(Exception):
+    def __init__(self, msg):
+        self.msg = dedent(msg).strip()
+
+    def __unicode__(self):
+        return self.msg
+
+    __str__ = __unicode__
+
+
+class DockerNotFoundMac(UserError):
+    def __init__(self):
+        super(DockerNotFoundMac, self).__init__("""
+        Couldn't connect to Docker daemon. You might need to install docker-osx:
+
+        https://github.com/noplay/docker-osx
+        """)
+
+
+class DockerNotFoundUbuntu(UserError):
+    def __init__(self):
+        super(DockerNotFoundUbuntu, self).__init__("""
+        Couldn't connect to Docker daemon. You might need to install Docker:
+
+        http://docs.docker.io/en/latest/installation/ubuntulinux/
+        """)
+
+
+class DockerNotFoundGeneric(UserError):
+    def __init__(self):
+        super(DockerNotFoundGeneric, self).__init__("""
+        Couldn't connect to Docker daemon. You might need to install Docker:
+
+        http://docs.docker.io/en/latest/installation/
+        """)
+
+
+class ConnectionErrorBoot2Docker(UserError):
+    def __init__(self):
+        super(ConnectionErrorBoot2Docker, self).__init__("""
+        Couldn't connect to Docker daemon - you might need to run `boot2docker up`.
+        """)
+
+
+class ConnectionErrorGeneric(UserError):
+    def __init__(self, url):
+        super(ConnectionErrorGeneric, self).__init__("""
+        Couldn't connect to Docker daemon at %s - is it running?
+
+        If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable.
+        """ % url)
+
+
+class ComposeFileNotFound(UserError):
+    def __init__(self, filename):
+        super(ComposeFileNotFound, self).__init__("""
+        Can't find %s. Are you in the right directory?
+        """ % filename)

compose/cli/formatter.py

@@ -0,0 +1,23 @@
+from __future__ import unicode_literals
+from __future__ import absolute_import
+import os
+import texttable
+
+
+def get_tty_width():
+    tty_size = os.popen('stty size', 'r').read().split()
+    if len(tty_size) != 2:
+        return 80
+    _, width = tty_size
+    return int(width)
+
+
+class Formatter(object):
+    def table(self, headers, rows):
+        table = texttable.Texttable(max_width=get_tty_width())
+        table.set_cols_dtype(['t' for h in headers])
+        table.add_rows([headers] + rows)
+        table.set_deco(table.HEADER)
+        table.set_chars(['-', '|', '+', '-'])
+
+        return table.draw()

compose/cli/log_printer.py

@@ -0,0 +1,79 @@
+from __future__ import unicode_literals
+from __future__ import absolute_import
+import sys
+
+from itertools import cycle
+
+from .multiplexer import Multiplexer, STOP
+from . import colors
+from .utils import split_buffer
+
+
+class LogPrinter(object):
+    def __init__(self, containers, attach_params=None, output=sys.stdout, monochrome=False):
+        self.containers = containers
+        self.attach_params = attach_params or {}
+        self.prefix_width = self._calculate_prefix_width(containers)
+        self.generators = self._make_log_generators(monochrome)
+        self.output = output
+
+    def run(self):
+        mux = Multiplexer(self.generators)
+        for line in mux.loop():
+            self.output.write(line)
+
+    def _calculate_prefix_width(self, containers):
+        """
+        Calculate the maximum width of container names so we can make the log
+        prefixes line up like so:
+
+        db_1  | Listening
+        web_1 | Listening
+        """
+        prefix_width = 0
+        for container in containers:
+            prefix_width = max(prefix_width, len(container.name_without_project))
+        return prefix_width
+
+    def _make_log_generators(self, monochrome):
+        color_fns = cycle(colors.rainbow())
+        generators = []
+
+        for container in self.containers:
+            if monochrome:
+                color_fn = lambda s: s
+            else:
+                color_fn = color_fns.next()
+            generators.append(self._make_log_generator(container, color_fn))
+
+        return generators
+
+    def _make_log_generator(self, container, color_fn):
+        prefix = color_fn(self._generate_prefix(container)).encode('utf-8')
+        # Attach to container before log printer starts running
+        line_generator = split_buffer(self._attach(container), '\n')
+
+        for line in line_generator:
+            yield prefix + line
+
+        exit_code = container.wait()
+        yield color_fn("%s exited with code %s\n" % (container.name, exit_code))
+        yield STOP
+
+    def _generate_prefix(self, container):
+        """
+        Generate the prefix for a log line without colour
+        """
+        name = container.name_without_project
+        padding = ' ' * (self.prefix_width - len(name))
+        return ''.join([name, padding, ' | '])
+
+    def _attach(self, container):
+        params = {
+            'stdout': True,
+            'stderr': True,
+            'stream': True,
+        }
+        params.update(self.attach_params)
+        params = dict((name, 1 if value else 0) for (name, value) in list(params.items()))
+        return container.attach(**params)

compose/cli/main.py

@@ -0,0 +1,467 @@
+from __future__ import print_function
+from __future__ import unicode_literals
+import logging
+import sys
+import re
+import signal
+from operator import attrgetter
+
+from inspect import getdoc
+import dockerpty
+
+from .. import __version__
+from ..project import NoSuchService, ConfigurationError
+from ..service import BuildError, CannotBeScaledError
+from .command import Command
+from .formatter import Formatter
+from .log_printer import LogPrinter
+from .utils import yesno
+
+from docker.errors import APIError
+from .errors import UserError
+from .docopt_command import NoSuchCommand
+
+log = logging.getLogger(__name__)
+
+
+def main():
+    setup_logging()
+    try:
+        command = TopLevelCommand()
+        command.sys_dispatch()
+    except KeyboardInterrupt:
+        log.error("\nAborting.")
+        sys.exit(1)
+    except (UserError, NoSuchService, ConfigurationError) as e:
+        log.error(e.msg)
+        sys.exit(1)
+    except NoSuchCommand as e:
+        log.error("No such command: %s", e.command)
+        log.error("")
+        log.error("\n".join(parse_doc_section("commands:", getdoc(e.supercommand))))
+        sys.exit(1)
+    except APIError as e:
+        log.error(e.explanation)
+        sys.exit(1)
+    except BuildError as e:
+        log.error("Service '%s' failed to build: %s" % (e.service.name, e.reason))
+        sys.exit(1)
+
+
+def setup_logging():
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setFormatter(logging.Formatter())
+    console_handler.setLevel(logging.INFO)
+    root_logger = logging.getLogger()
+    root_logger.addHandler(console_handler)
+    root_logger.setLevel(logging.DEBUG)
+
+    # Disable requests logging
+    logging.getLogger("requests").propagate = False
+
+
+# stolen from docopt master
+def parse_doc_section(name, source):
+    pattern = re.compile('^([^\n]*' + name + '[^\n]*\n?(?:[ \t].*?(?:\n|$))*)',
+                         re.IGNORECASE | re.MULTILINE)
+    return [s.strip() for s in pattern.findall(source)]
+
+
+class TopLevelCommand(Command):
+    """Fast, isolated development environments using Docker.
+
+    Usage:
+      compose [options] [COMMAND] [ARGS...]
+      compose -h|--help
+
+    Options:
+      --verbose                 Show more output
+      --version                 Print version and exit
+      -f, --file FILE           Specify an alternate compose file (default: compose.yml)
+      -p, --project-name NAME   Specify an alternate project name (default: directory name)
+
+    Commands:
+      build     Build or rebuild services
+      help      Get help on a command
+      kill      Kill containers
+      logs      View output from containers
+      port      Print the public port for a port binding
+      ps        List containers
+      pull      Pulls service images
+      rm        Remove stopped containers
+      run       Run a one-off command
+      scale     Set number of containers for a service
+      start     Start services
+      stop      Stop services
+      restart   Restart services
+      up        Create and start containers
+
+    """
+    def docopt_options(self):
+        options = super(TopLevelCommand, self).docopt_options()
+        options['version'] = "compose %s" % __version__
+        return options
+
+    def build(self, project, options):
+        """
+        Build or rebuild services.
+
+        Services are built once and then tagged as `project_service`,
+        e.g. `composetest_db`. If you change a service's `Dockerfile` or the
+        contents of its build directory, you can run `compose build` to rebuild it.
+
+        Usage: build [options] [SERVICE...]
+
+        Options:
+            --no-cache  Do not use cache when building the image.
+        """
+        no_cache = bool(options.get('--no-cache', False))
+        project.build(service_names=options['SERVICE'], no_cache=no_cache)
+
+    def help(self, project, options):
+        """
+        Get help on a command.
+
+        Usage: help COMMAND
+        """
+        command = options['COMMAND']
+        if not hasattr(self, command):
+            raise NoSuchCommand(command, self)
+        raise SystemExit(getdoc(getattr(self, command)))
+
+    def kill(self, project, options):
+        """
+        Force stop service containers.
+
+        Usage: kill [options] [SERVICE...]
+
+        Options:
+            -s SIGNAL         SIGNAL to send to the container.
+                              Default signal is SIGKILL.
+        """
+        signal = options.get('-s', 'SIGKILL')
+
+        project.kill(service_names=options['SERVICE'], signal=signal)
+
+    def logs(self, project, options):
+        """
+        View output from containers.
+
+        Usage: logs [options] [SERVICE...]
+
+        Options:
+            --no-color  Produce monochrome output.
+        """
+        containers = project.containers(service_names=options['SERVICE'], stopped=True)
+
+        monochrome = options['--no-color']
+        print("Attaching to", list_containers(containers))
+        LogPrinter(containers, attach_params={'logs': True}, monochrome=monochrome).run()
+
+    def port(self, project, options):
+        """
+        Print the public port for a port binding.
+
+        Usage: port [options] SERVICE PRIVATE_PORT
+
+        Options:
+            --protocol=proto  tcp or udp (defaults to tcp)
+            --index=index     index of the container if there are multiple
+                              instances of a service (defaults to 1)
+        """
+        service = project.get_service(options['SERVICE'])
+        try:
+            container = service.get_container(number=options.get('--index') or 1)
+        except ValueError as e:
+            raise UserError(str(e))
+        print(container.get_local_port(
+            options['PRIVATE_PORT'],
+            protocol=options.get('--protocol') or 'tcp') or '')
+
+    def ps(self, project, options):
+        """
+        List containers.
+
+        Usage: ps [options] [SERVICE...]
+
+        Options:
+            -q    Only display IDs
+        """
+        containers = sorted(
+            project.containers(service_names=options['SERVICE'], stopped=True) +
+            project.containers(service_names=options['SERVICE'], one_off=True),
+            key=attrgetter('name'))
+
+        if options['-q']:
+            for container in containers:
+                print(container.id)
+        else:
+            headers = [
+                'Name',
+                'Command',
+                'State',
+                'Ports',
+            ]
+            rows = []
+            for container in containers:
+                command = container.human_readable_command
+                if len(command) > 30:
+                    command = '%s ...' % command[:26]
+                rows.append([
+                    container.name,
+                    command,
+                    container.human_readable_state,
+                    container.human_readable_ports,
+                ])
+            print(Formatter().table(headers, rows))
+
+    def pull(self, project, options):
+        """
+        Pulls images for services.
+
+        Usage: pull [options] [SERVICE...]
+
+        Options:
+            --allow-insecure-ssl    Allow insecure connections to the docker
+                                    registry
+        """
+        insecure_registry = options['--allow-insecure-ssl']
+        project.pull(
+            service_names=options['SERVICE'],
+            insecure_registry=insecure_registry
+        )
+
+    def rm(self, project, options):
+        """
+        Remove stopped service containers.
+
+        Usage: rm [options] [SERVICE...]
+
+        Options:
+            --force   Don't ask to confirm removal
+            -v        Remove volumes associated with containers
+        """
+        all_containers = project.containers(service_names=options['SERVICE'], stopped=True)
+        stopped_containers = [c for c in all_containers if not c.is_running]
+
+        if len(stopped_containers) > 0:
+            print("Going to remove", list_containers(stopped_containers))
+            if options.get('--force') \
+                    or yesno("Are you sure? [yN] ", default=False):
+                project.remove_stopped(
+                    service_names=options['SERVICE'],
+                    v=options.get('-v', False)
+                )
+        else:
+            print("No stopped containers")
+
+    def run(self, project, options):
+        """
+        Run a one-off command on a service.
+
+        For example:
+
+            $ compose run web python manage.py shell
+
+        By default, linked services will be started, unless they are already
+        running. If you do not want to start linked services, use
+        `compose run --no-deps SERVICE COMMAND [ARGS...]`.
+
+        Usage: run [options] [-e KEY=VAL...] SERVICE [COMMAND] [ARGS...]
+
+        Options:
+            --allow-insecure-ssl  Allow insecure connections to the docker
+                                  registry
+            -d                    Detached mode: Run container in the background, print
+                                  new container name.
+            --entrypoint CMD      Override the entrypoint of the image.
+            -e KEY=VAL            Set an environment variable (can be used multiple times)
+            --no-deps             Don't start linked services.
+            --rm                  Remove container after run. Ignored in detached mode.
+            --service-ports       Run command with the service's ports enabled and mapped
+                                  to the host.
+            -T                    Disable pseudo-tty allocation. By default `compose run`
+                                  allocates a TTY.
+        """
+        service = project.get_service(options['SERVICE'])
+
+        insecure_registry = options['--allow-insecure-ssl']
+
+        if not options['--no-deps']:
+            deps = service.get_linked_names()
+
+            if len(deps) > 0:
+                project.up(
+                    service_names=deps,
+                    start_links=True,
+                    recreate=False,
+                    insecure_registry=insecure_registry,
+                    detach=options['-d']
+                )
+
+        tty = True
+        if options['-d'] or options['-T'] or not sys.stdin.isatty():
+            tty = False
+
+        if options['COMMAND']:
+            command = [options['COMMAND']] + options['ARGS']
+        else:
+            command = service.options.get('command')
+
+        container_options = {
+            'command': command,
+            'tty': tty,
+            'stdin_open': not options['-d'],
+            'detach': options['-d'],
+        }
+
+        if options['-e']:
+            for option in options['-e']:
+                if 'environment' not in service.options:
+                    service.options['environment'] = {}
+                k, v = option.split('=', 1)
+                service.options['environment'][k] = v
+
+        if options['--entrypoint']:
+            container_options['entrypoint'] = options.get('--entrypoint')
+        container = service.create_container(
+            one_off=True,
+            insecure_registry=insecure_registry,
+            **container_options
+        )
+
+        service_ports = None
+        if options['--service-ports']:
+            service_ports = service.options['ports']
+        if options['-d']:
+            service.start_container(container, ports=service_ports, one_off=True)
+            print(container.name)
+        else:
+            service.start_container(container, ports=service_ports, one_off=True)
+            dockerpty.start(project.client, container.id, interactive=not options['-T'])
+            exit_code = container.wait()
+            if options['--rm']:
+                log.info("Removing %s..." % container.name)
+                project.client.remove_container(container.id)
+            sys.exit(exit_code)
+
+    def scale(self, project, options):
+        """
+        Set number of containers to run for a service.
+
+        Numbers are specified in the form `service=num` as arguments.
+        For example:
+
+            $ compose scale web=2 worker=3
+
+        Usage: scale [SERVICE=NUM...]
+        """
+        for s in options['SERVICE=NUM']:
+            if '=' not in s:
+                raise UserError('Arguments to scale should be in the form service=num')
+            service_name, num = s.split('=', 1)
+            try:
+                num = int(num)
+            except ValueError:
+                raise UserError('Number of containers for service "%s" is not a '
+                                'number' % service_name)
+            try:
+                project.get_service(service_name).scale(num)
+            except CannotBeScaledError:
+                raise UserError(
+                    'Service "%s" cannot be scaled because it specifies a port '
+                    'on the host. If multiple containers for this service were '
+                    'created, the port would clash.\n\nRemove the ":" from the '
+                    'port definition in compose.yml so Docker can choose a random '
+                    'port for each container.' % service_name)
+
+    def start(self, project, options):
+        """
+        Start existing containers.
+
+        Usage: start [SERVICE...]
+        """
+        project.start(service_names=options['SERVICE'])
+
+    def stop(self, project, options):
+        """
+        Stop running containers without removing them.
+
+        They can be started again with `compose start`.
+
+        Usage: stop [SERVICE...]
+        """
+        project.stop(service_names=options['SERVICE'])
+
+    def restart(self, project, options):
+        """
+        Restart running containers.
+
+        Usage: restart [SERVICE...]
+        """
+        project.restart(service_names=options['SERVICE'])
+
+    def up(self, project, options):
+        """
+        Build, (re)create, start and attach to containers for a service.
+
+        By default, `compose up` will aggregate the output of each container, and
+        when it exits, all containers will be stopped. If you run `compose up -d`,
+        it'll start the containers in the background and leave them running.
+
+        If there are existing containers for a service, `compose up` will stop
+        and recreate them (preserving mounted volumes with volumes-from),
+        so that changes in `compose.yml` are picked up. If you do not want existing
+        containers to be recreated, `compose up --no-recreate` will re-use existing
+        containers.
+
+        Usage: up [options] [SERVICE...]
+
+        Options:
+            --allow-insecure-ssl  Allow insecure connections to the docker
+                                  registry
+            -d                    Detached mode: Run containers in the background,
+                                  print new container names.
+            --no-color            Produce monochrome output.
+            --no-deps             Don't start linked services.
+            --no-recreate         If containers already exist, don't recreate them.
+            --no-build            Don't build an image, even if it's missing
+        """
+        insecure_registry = options['--allow-insecure-ssl']
+        detached = options['-d']
+
+        monochrome = options['--no-color']
+
+        start_links = not options['--no-deps']
+        recreate = not options['--no-recreate']
+        service_names = options['SERVICE']
+
+        project.up(
+            service_names=service_names,
+            start_links=start_links,
+            recreate=recreate,
+            insecure_registry=insecure_registry,
+            detach=options['-d'],
+            do_build=not options['--no-build'],
+        )
+
+        to_attach = [c for s in project.get_services(service_names) for c in s.containers()]
+
+        if not detached:
+            print("Attaching to", list_containers(to_attach))
+            log_printer = LogPrinter(to_attach, attach_params={"logs": True}, monochrome=monochrome)
+
+            try:
+                log_printer.run()
+            finally:
+                def handler(signal, frame):
+                    project.kill(service_names=service_names)
+                    sys.exit(0)
+                signal.signal(signal.SIGINT, handler)
+
+                print("Gracefully stopping... (press Ctrl+C again to force)")
+                project.stop(service_names=service_names)
+
+
+def list_containers(containers):
+    return ", ".join(c.name for c in containers)

compose/cli/multiplexer.py

@@ -0,0 +1,42 @@
+from __future__ import absolute_import
+from threading import Thread
+
+try:
+    from Queue import Queue, Empty
+except ImportError:
+    from queue import Queue, Empty  # Python 3.x
+
+
+# Yield STOP from an input generator to stop the
+# top-level loop without processing any more input.
+STOP = object()
+
+
+class Multiplexer(object):
+    def __init__(self, generators):
+        self.generators = generators
+        self.queue = Queue()
+
+    def loop(self):
+        self._init_readers()
+
+        while True:
+            try:
+                item = self.queue.get(timeout=0.1)
+                if item is STOP:
+                    break
+                else:
+                    yield item
+            except Empty:
+                pass
+
+    def _init_readers(self):
+        for generator in self.generators:
+            t = Thread(target=_enqueue_output, args=(generator, self.queue))
+            t.daemon = True
+            t.start()
+
+
+def _enqueue_output(generator, queue):
+    for item in generator:
+        queue.put(item)

compose/cli/utils.py

@@ -0,0 +1,103 @@
+from __future__ import unicode_literals
+from __future__ import absolute_import
+from __future__ import division
+import datetime
+import os
+import subprocess
+import platform
+
+
+def yesno(prompt, default=None):
+    """
+    Prompt the user for a yes or no.
+
+    Can optionally specify a default value, which will only be
+    used if they enter a blank line.
+
+    Unrecognised input (anything other than "y", "n", "yes",
+    "no" or "") will return None.
+    """
+    answer = raw_input(prompt).strip().lower()
+
+    if answer == "y" or answer == "yes":
+        return True
+    elif answer == "n" or answer == "no":
+        return False
+    elif answer == "":
+        return default
+    else:
+        return None
+
+
+# http://stackoverflow.com/a/5164027
+def prettydate(d):
+    diff = datetime.datetime.utcnow() - d
+    s = diff.seconds
+    if diff.days > 7 or diff.days < 0:
+        return d.strftime('%d %b %y')
+    elif diff.days == 1:
+        return '1 day ago'
+    elif diff.days > 1:
+        return '{0} days ago'.format(diff.days)
+    elif s <= 1:
+        return 'just now'
+    elif s < 60:
+        return '{0} seconds ago'.format(s)
+    elif s < 120:
+        return '1 minute ago'
+    elif s < 3600:
+        return '{0} minutes ago'.format(s / 60)
+    elif s < 7200:
+        return '1 hour ago'
+    else:
+        return '{0} hours ago'.format(s / 3600)
+
+
+def mkdir(path, permissions=0o700):
+    if not os.path.exists(path):
+        os.mkdir(path)
+
+    os.chmod(path, permissions)
+
+    return path
+
+
+def split_buffer(reader, separator):
+    """
+    Given a generator which yields strings and a separator string,
+    joins all input, splits on the separator and yields each chunk.
+
+    Unlike string.split(), each chunk includes the trailing
+    separator, except for the last one if none was found on the end
+    of the input.
+    """
+    buffered = str('')
+    separator = str(separator)
+
+    for data in reader:
+        buffered += data
+        while True:
+            index = buffered.find(separator)
+            if index == -1:
+                break
+            yield buffered[:index + 1]
+            buffered = buffered[index + 1:]
+
+    if len(buffered) > 0:
+        yield buffered
+
+
+def call_silently(*args, **kwargs):
+    """
+    Like subprocess.call(), but redirects stdout and stderr to /dev/null.
+    """
+    with open(os.devnull, 'w') as shutup:
+        return subprocess.call(*args, stdout=shutup, stderr=shutup, **kwargs)
+
+
+def is_mac():
+    return platform.system() == 'Darwin'
+
+
+def is_ubuntu():
+    return platform.system() == 'Linux' and platform.linux_distribution()[0] == 'Ubuntu'

compose/cli/verbose_proxy.py

@@ -0,0 +1,58 @@
+
+import functools
+from itertools import chain
+import logging
+import pprint
+
+import six
+
+
+def format_call(args, kwargs):
+    args = (repr(a) for a in args)
+    kwargs = ("{0!s}={1!r}".format(*item) for item in six.iteritems(kwargs))
+    return "({0})".format(", ".join(chain(args, kwargs)))
+
+
+def format_return(result, max_lines):
+    if isinstance(result, (list, tuple, set)):
+        return "({0} with {1} items)".format(type(result).__name__, len(result))
+
+    if result:
+        lines = pprint.pformat(result).split('\n')
+        extra = '\n...' if len(lines) > max_lines else ''
+        return '\n'.join(lines[:max_lines]) + extra
+
+    return result
+
+
+class VerboseProxy(object):
+    """Proxy all function calls to another class and log method name, arguments
+    and return values for each call.
+    """
+
+    def __init__(self, obj_name, obj, log_name=None, max_lines=10):
+        self.obj_name = obj_name
+        self.obj = obj
+        self.max_lines = max_lines
+        self.log = logging.getLogger(log_name or __name__)
+
+    def __getattr__(self, name):
+        attr = getattr(self.obj, name)
+
+        if not six.callable(attr):
+            return attr
+
+        return functools.partial(self.proxy_callable, name)
+
+    def proxy_callable(self, call_name, *args, **kwargs):
+        self.log.info("%s %s <- %s",
+                      self.obj_name,
+                      call_name,
+                      format_call(args, kwargs))
+
+        result = getattr(self.obj, call_name)(*args, **kwargs)
+        self.log.info("%s %s -> %s",
+                      self.obj_name,
+                      call_name,
+                      format_return(result, self.max_lines))
+        return result

compose/container.py

@@ -0,0 +1,181 @@
+from __future__ import unicode_literals
+from __future__ import absolute_import
+
+import six
+
+
+class Container(object):
+    """
+    Represents a Docker container, constructed from the output of
+    GET /containers/:id:/json.
+    """
+    def __init__(self, client, dictionary, has_been_inspected=False):
+        self.client = client
+        self.dictionary = dictionary
+        self.has_been_inspected = has_been_inspected
+
+    @classmethod
+    def from_ps(cls, client, dictionary, **kwargs):
+        """
+        Construct a container object from the output of GET /containers/json.
+        """
+        new_dictionary = {
+            'Id': dictionary['Id'],
+            'Image': dictionary['Image'],
+            'Name': '/' + get_container_name(dictionary),
+        }
+        return cls(client, new_dictionary, **kwargs)
+
+    @classmethod
+    def from_id(cls, client, id):
+        return cls(client, client.inspect_container(id))
+
+    @classmethod
+    def create(cls, client, **options):
+        response = client.create_container(**options)
+        return cls.from_id(client, response['Id'])
+
+    @property
+    def id(self):
+        return self.dictionary['Id']
+
+    @property
+    def image(self):
+        return self.dictionary['Image']
+
+    @property
+    def short_id(self):
+        return self.id[:10]
+
+    @property
+    def name(self):
+        return self.dictionary['Name'][1:]
+
+    @property
+    def name_without_project(self):
+        return '_'.join(self.dictionary['Name'].split('_')[1:])
+
+    @property
+    def number(self):
+        try:
+            return int(self.name.split('_')[-1])
+        except ValueError:
+            return None
+
+    @property
+    def ports(self):
+        self.inspect_if_not_inspected()
+        return self.get('NetworkSettings.Ports') or {}
+
+    @property
+    def human_readable_ports(self):
+        def format_port(private, public):
+            if not public:
+                return private
+            return '{HostIp}:{HostPort}->{private}'.format(
+                private=private, **public[0])
+
+        return ', '.join(format_port(*item)
+                         for item in sorted(six.iteritems(self.ports)))
+
+    @property
+    def human_readable_state(self):
+        if self.is_running:
+            return 'Ghost' if self.get('State.Ghost') else 'Up'
+        else:
+            return 'Exit %s' % self.get('State.ExitCode')
+
+    @property
+    def human_readable_command(self):
+        entrypoint = self.get('Config.Entrypoint') or []
+        cmd = self.get('Config.Cmd') or []
+        return ' '.join(entrypoint + cmd)
+
+    @property
+    def environment(self):
+        return dict(var.split("=", 1) for var in self.get('Config.Env') or [])
+
+    @property
+    def is_running(self):
+        return self.get('State.Running')
+
+    def get(self, key):
+        """Return a value from the container or None if the value is not set.
+
+        :param key: a string using dotted notation for nested dictionary
+                    lookups
+        """
+        self.inspect_if_not_inspected()
+
+        def get_value(dictionary, key):
+            return (dictionary or {}).get(key)
+
+        return reduce(get_value, key.split('.'), self.dictionary)
+
+    def get_local_port(self, port, protocol='tcp'):
+        port = self.ports.get("%s/%s" % (port, protocol))
+        return "{HostIp}:{HostPort}".format(**port[0]) if port else None
+
+    def start(self, **options):
+        return self.client.start(self.id, **options)
+
+    def stop(self, **options):
+        return self.client.stop(self.id, **options)
+
+    def kill(self, **options):
+        return self.client.kill(self.id, **options)
+
+    def restart(self):
+        return self.client.restart(self.id)
+
+    def remove(self, **options):
+        return self.client.remove_container(self.id, **options)
+
+    def inspect_if_not_inspected(self):
+        if not self.has_been_inspected:
+            self.inspect()
+
+    def wait(self):
+        return self.client.wait(self.id)
+
+    def logs(self, *args, **kwargs):
+        return self.client.logs(self.id, *args, **kwargs)
+
+    def inspect(self):
+        self.dictionary = self.client.inspect_container(self.id)
+        self.has_been_inspected = True
+        return self.dictionary
+
+    def links(self):
+        links = []
+        for container in self.client.containers():
+            for name in container['Names']:
+                bits = name.split('/')
+                if len(bits) > 2 and bits[1] == self.name:
+                    links.append(bits[2])
+        return links
+
+    def attach(self, *args, **kwargs):
+        return self.client.attach(self.id, *args, **kwargs)
+
+    def attach_socket(self, **kwargs):
+        return self.client.attach_socket(self.id, **kwargs)
+
+    def __repr__(self):
+        return '<Container: %s>' % self.name
+
+    def __eq__(self, other):
+        if type(self) != type(other):
+            return False
+        return self.id == other.id
+
+
+def get_container_name(container):
+    if not container.get('Name') and not container.get('Names'):
+        return None
+    # inspect
+    if 'Name' in container:
+        return container['Name']
+    # ps
+    shortest_name = min(container['Names'], key=lambda n: len(n.split('/')))
+    return shortest_name.split('/')[-1]

compose/progress_stream.py

@@ -0,0 +1,85 @@
+import json
+import os
+import codecs
+
+
+class StreamOutputError(Exception):
+    pass
+
+
+def stream_output(output, stream):
+    is_terminal = hasattr(stream, 'fileno') and os.isatty(stream.fileno())
+    stream = codecs.getwriter('utf-8')(stream)
+    all_events = []
+    lines = {}
+    diff = 0
+
+    for chunk in output:
+        event = json.loads(chunk)
+        all_events.append(event)
+
+        if 'progress' in event or 'progressDetail' in event:
+            image_id = event.get('id')
+            if not image_id:
+                continue
+
+            if image_id in lines:
+                diff = len(lines) - lines[image_id]
+            else:
+                lines[image_id] = len(lines)
+                stream.write("\n")
+                diff = 0
+
+            if is_terminal:
+                # move cursor up `diff` rows
+                stream.write("%c[%dA" % (27, diff))
+
+        print_output_event(event, stream, is_terminal)
+
+        if 'id' in event and is_terminal:
+            # move cursor back down
+            stream.write("%c[%dB" % (27, diff))
+
+        stream.flush()
+
+    return all_events
+
+
+def print_output_event(event, stream, is_terminal):
+    if 'errorDetail' in event:
+        raise StreamOutputError(event['errorDetail']['message'])
+
+    terminator = ''
+
+    if is_terminal and 'stream' not in event:
+        # erase current line
+        stream.write("%c[2K\r" % 27)
+        terminator = "\r"
+        pass
+    elif 'progressDetail' in event:
+        return
+
+    if 'time' in event:
+        stream.write("[%s] " % event['time'])
+
+    if 'id' in event:
+        stream.write("%s: " % event['id'])
+
+    if 'from' in event:
+        stream.write("(from %s) " % event['from'])
+
+    status = event.get('status', '')
+
+    if 'progress' in event:
+        stream.write("%s %s%s" % (status, event['progress'], terminator))
+    elif 'progressDetail' in event:
+        detail = event['progressDetail']
+        if 'current' in detail:
+            percentage = float(detail['current']) / float(detail['total']) * 100
+            stream.write('%s (%.1f%%)%s' % (status, percentage, terminator))
+        else:
+            stream.write('%s%s' % (status, terminator))
+    elif 'stream' in event:
+        stream.write("%s%s" % (event['stream'], terminator))
+    else:
+        stream.write("%s%s\n" % (status, terminator))

compose/project.py

@@ -0,0 +1,241 @@
+from __future__ import unicode_literals
+from __future__ import absolute_import
+import logging
+
+from .service import Service
+from .container import Container
+from docker.errors import APIError
+
+log = logging.getLogger(__name__)
+
+
+def sort_service_dicts(services):
+    # Topological sort (Cormen/Tarjan algorithm).
+    unmarked = services[:]
+    temporary_marked = set()
+    sorted_services = []
+
+    get_service_names = lambda links: [link.split(':')[0] for link in links]
+
+    def visit(n):
+        if n['name'] in temporary_marked:
+            if n['name'] in get_service_names(n.get('links', [])):
+                raise DependencyError('A service can not link to itself: %s' % n['name'])
+            if n['name'] in n.get('volumes_from', []):
+                raise DependencyError('A service can not mount itself as volume: %s' % n['name'])
+            else:
+                raise DependencyError('Circular import between %s' % ' and '.join(temporary_marked))
+        if n in unmarked:
+            temporary_marked.add(n['name'])
+            dependents = [m for m in services if (n['name'] in get_service_names(m.get('links', []))) or (n['name'] in m.get('volumes_from', []))]
+            for m in dependents:
+                visit(m)
+            temporary_marked.remove(n['name'])
+            unmarked.remove(n)
+            sorted_services.insert(0, n)
+
+    while unmarked:
+        visit(unmarked[-1])
+
+    return sorted_services
+
+
+class Project(object):
+    """
+    A collection of services.
+    """
+    def __init__(self, name, services, client):
+        self.name = name
+        self.services = services
+        self.client = client
+
+    @classmethod
+    def from_dicts(cls, name, service_dicts, client):
+        """
+        Construct a ServiceCollection from a list of dicts representing services.
+        """
+        project = cls(name, [], client)
+        for service_dict in sort_service_dicts(service_dicts):
+            links = project.get_links(service_dict)
+            volumes_from = project.get_volumes_from(service_dict)
+
+            project.services.append(Service(client=client, project=name, links=links, volumes_from=volumes_from, **service_dict))
+        return project
+
+    @classmethod
+    def from_config(cls, name, config, client):
+        dicts = []
+        for service_name, service in list(config.items()):
+            if not isinstance(service, dict):
+                raise ConfigurationError('Service "%s" doesn\'t have any configuration options. All top level keys in your compose.yml must map to a dictionary of configuration options.' % service_name)
+            service['name'] = service_name
+            dicts.append(service)
+        return cls.from_dicts(name, dicts, client)
+
+    def get_service(self, name):
+        """
+        Retrieve a service by name. Raises NoSuchService
+        if the named service does not exist.
+        """
+        for service in self.services:
+            if service.name == name:
+                return service
+
+        raise NoSuchService(name)
+
+    def get_services(self, service_names=None, include_links=False):
+        """
+        Returns a list of this project's services filtered
+        by the provided list of names, or all services if service_names is None
+        or [].
+
+        If include_links is specified, returns a list including the links for
+        service_names, in order of dependency.
+
+        Preserves the original order of self.services where possible,
+        reordering as needed to resolve links.
+
+        Raises NoSuchService if any of the named services do not exist.
+        """
+        if service_names is None or len(service_names) == 0:
+            return self.get_services(
+                service_names=[s.name for s in self.services],
+                include_links=include_links
+            )
+        else:
+            unsorted = [self.get_service(name) for name in service_names]
+            services = [s for s in self.services if s in unsorted]
+
+            if include_links:
+                services = reduce(self._inject_links, services, [])
+
+            uniques = []
+            [uniques.append(s) for s in services if s not in uniques]
+            return uniques
+
+    def get_links(self, service_dict):
+        links = []
+        if 'links' in service_dict:
+            for link in service_dict.get('links', []):
+                if ':' in link:
+                    service_name, link_name = link.split(':', 1)
+                else:
+                    service_name, link_name = link, None
+                try:
+                    links.append((self.get_service(service_name), link_name))
+                except NoSuchService:
+                    raise ConfigurationError('Service "%s" has a link to service "%s" which does not exist.' % (service_dict['name'], service_name))
+            del service_dict['links']
+        return links
+
+    def get_volumes_from(self, service_dict):
+        volumes_from = []
+        if 'volumes_from' in service_dict:
+            for volume_name in service_dict.get('volumes_from', []):
+                try:
+                    service = self.get_service(volume_name)
+                    volumes_from.append(service)
+                except NoSuchService:
+                    try:
+                        container = Container.from_id(self.client, volume_name)
+                        volumes_from.append(container)
+                    except APIError:
+                        raise ConfigurationError('Service "%s" mounts volumes from "%s", which is not the name of a service or container.' % (service_dict['name'], volume_name))
+            del service_dict['volumes_from']
+        return volumes_from
+
+    def start(self, service_names=None, **options):
+        for service in self.get_services(service_names):
+            service.start(**options)
+
+    def stop(self, service_names=None, **options):
+        for service in reversed(self.get_services(service_names)):
+            service.stop(**options)
+
+    def kill(self, service_names=None, **options):
+        for service in reversed(self.get_services(service_names)):
+            service.kill(**options)
+
+    def restart(self, service_names=None, **options):
+        for service in self.get_services(service_names):
+            service.restart(**options)
+
+    def build(self, service_names=None, no_cache=False):
+        for service in self.get_services(service_names):
+            if service.can_be_built():
+                service.build(no_cache)
+            else:
+                log.info('%s uses an image, skipping' % service.name)
+
+    def up(self,
+           service_names=None,
+           start_links=True,
+           recreate=True,
+           insecure_registry=False,
+           detach=False,
+           do_build=True):
+        running_containers = []
+        for service in self.get_services(service_names, include_links=start_links):
+            if recreate:
+                for (_, container) in service.recreate_containers(
+                        insecure_registry=insecure_registry,
+                        detach=detach,
+                        do_build=do_build):
+                    running_containers.append(container)
+            else:
+                for container in service.start_or_create_containers(
+                        insecure_registry=insecure_registry,
+                        detach=detach,
+                        do_build=do_build):
+                    running_containers.append(container)
+
+        return running_containers
+
+    def pull(self, service_names=None, insecure_registry=False):
+        for service in self.get_services(service_names, include_links=True):
+            service.pull(insecure_registry=insecure_registry)
+
+    def remove_stopped(self, service_names=None, **options):
+        for service in self.get_services(service_names):
+            service.remove_stopped(**options)
+
+    def containers(self, service_names=None, stopped=False, one_off=False):
+        return [Container.from_ps(self.client, container)
+                for container in self.client.containers(all=stopped)
+                for service in self.get_services(service_names)
+                if service.has_container(container, one_off=one_off)]
+
+    def _inject_links(self, acc, service):
+        linked_names = service.get_linked_names()
+
+        if len(linked_names) > 0:
+            linked_services = self.get_services(
+                service_names=linked_names,
+                include_links=True
+            )
+        else:
+            linked_services = []
+
+        linked_services.append(service)
+        return acc + linked_services
+
+
+class NoSuchService(Exception):
+    def __init__(self, name):
+        self.name = name
+        self.msg = "No such service: %s" % self.name
+
+    def __str__(self):
+        return self.msg
+
+
+class ConfigurationError(Exception):
+    def __init__(self, msg):
+        self.msg = msg
+
+    def __str__(self):
+        return self.msg
+
+
+class DependencyError(ConfigurationError):
+    pass

compose/service.py

@@ -0,0 +1,665 @@
+from __future__ import unicode_literals
+from __future__ import absolute_import
+from collections import namedtuple
+import logging
+import re
+import os
+from operator import attrgetter
+import sys
+
+from docker.errors import APIError
+
+from .container import Container, get_container_name
+from .progress_stream import stream_output, StreamOutputError
+
+log = logging.getLogger(__name__)
+
+
+DOCKER_CONFIG_KEYS = [
+    'cap_add',
+    'cap_drop',
+    'cpu_shares',
+    'command',
+    'detach',
+    'dns',
+    'dns_search',
+    'domainname',
+    'entrypoint',
+    'env_file',
+    'environment',
+    'hostname',
+    'image',
+    'mem_limit',
+    'net',
+    'ports',
+    'privileged',
+    'restart',
+    'stdin_open',
+    'tty',
+    'user',
+    'volumes',
+    'volumes_from',
+    'working_dir',
+]
+DOCKER_CONFIG_HINTS = {
+    'cpu_share' : 'cpu_shares',
+    'link'      : 'links',
+    'port'      : 'ports',
+    'privilege' : 'privileged',
+    'priviliged': 'privileged',
+    'privilige' : 'privileged',
+    'volume'    : 'volumes',
+    'workdir'   : 'working_dir',
+}
+
+DOCKER_START_KEYS = [
+    'cap_add',
+    'cap_drop',
+    'dns',
+    'dns_search',
+    'env_file',
+    'net',
+    'privileged',
+    'restart',
+]
+
+VALID_NAME_CHARS = '[a-zA-Z0-9]'
+
+
+class BuildError(Exception):
+    def __init__(self, service, reason):
+        self.service = service
+        self.reason = reason
+
+
+class CannotBeScaledError(Exception):
+    pass
+
+
+class ConfigError(ValueError):
+    pass
+
+
+VolumeSpec = namedtuple('VolumeSpec', 'external internal mode')
+
+
+ServiceName = namedtuple('ServiceName', 'project service number')
+
+
+class Service(object):
+    def __init__(self, name, client=None, project='default', links=None, external_links=None, volumes_from=None, **options):
+        if not re.match('^%s+$' % VALID_NAME_CHARS, name):
+            raise ConfigError('Invalid service name "%s" - only %s are allowed' % (name, VALID_NAME_CHARS))
+        if not re.match('^%s+$' % VALID_NAME_CHARS, project):
+            raise ConfigError('Invalid project name "%s" - only %s are allowed' % (project, VALID_NAME_CHARS))
+        if 'image' in options and 'build' in options:
+            raise ConfigError('Service %s has both an image and build path specified. A service can either be built to image or use an existing image, not both.' % name)
+
+        supported_options = DOCKER_CONFIG_KEYS + ['build', 'expose',
+                                                  'external_links']
+
+        for k in options:
+            if k not in supported_options:
+                msg = "Unsupported config option for %s service: '%s'" % (name, k)
+                if k in DOCKER_CONFIG_HINTS:
+                    msg += " (did you mean '%s'?)" % DOCKER_CONFIG_HINTS[k]
+                raise ConfigError(msg)
+
+        self.name = name
+        self.client = client
+        self.project = project
+        self.links = links or []
+        self.external_links = external_links or []
+        self.volumes_from = volumes_from or []
+        self.options = options
+
+    def containers(self, stopped=False, one_off=False):
+        return [Container.from_ps(self.client, container)
+                for container in self.client.containers(all=stopped)
+                if self.has_container(container, one_off=one_off)]
+
+    def has_container(self, container, one_off=False):
+        """Return True if `container` was created to fulfill this service."""
+        name = get_container_name(container)
+        if not name or not is_valid_name(name, one_off):
+            return False
+        project, name, _number = parse_name(name)
+        return project == self.project and name == self.name
+
+    def get_container(self, number=1):
+        """Return a :class:`compose.container.Container` for this service. The
+        container must be active, and match `number`.
+        """
+        for container in self.client.containers():
+            if not self.has_container(container):
+                continue
+            _, _, container_number = parse_name(get_container_name(container))
+            if container_number == number:
+                return Container.from_ps(self.client, container)
+
+        raise ValueError("No container found for %s_%s" % (self.name, number))
+
+    def start(self, **options):
+        for c in self.containers(stopped=True):
+            self.start_container_if_stopped(c, **options)
+
+    def stop(self, **options):
+        for c in self.containers():
+            log.info("Stopping %s..." % c.name)
+            c.stop(**options)
+
+    def kill(self, **options):
+        for c in self.containers():
+            log.info("Killing %s..." % c.name)
+            c.kill(**options)
+
+    def restart(self, **options):
+        for c in self.containers():
+            log.info("Restarting %s..." % c.name)
+            c.restart(**options)
+
+    def scale(self, desired_num):
+        """
+        Adjusts the number of containers to the specified number and ensures
+        they are running.
+
+        - creates containers until there are at least `desired_num`
+        - stops containers until there are at most `desired_num` running
+        - starts containers until there are at least `desired_num` running
+        - removes all stopped containers
+        """
+        if not self.can_be_scaled():
+            raise CannotBeScaledError()
+
+        # Create enough containers
+        containers = self.containers(stopped=True)
+        while len(containers) < desired_num:
+            containers.append(self.create_container(detach=True))
+
+        running_containers = []
+        stopped_containers = []
+        for c in containers:
+            if c.is_running:
+                running_containers.append(c)
+            else:
+                stopped_containers.append(c)
+        running_containers.sort(key=lambda c: c.number)
+        stopped_containers.sort(key=lambda c: c.number)
+
+        # Stop containers
+        while len(running_containers) > desired_num:
+            c = running_containers.pop()
+            log.info("Stopping %s..." % c.name)
+            c.stop(timeout=1)
+            stopped_containers.append(c)
+
+        # Start containers
+        while len(running_containers) < desired_num:
+            c = stopped_containers.pop(0)
+            log.info("Starting %s..." % c.name)
+            self.start_container(c)
+            running_containers.append(c)
+
+        self.remove_stopped()
+
+    def remove_stopped(self, **options):
+        for c in self.containers(stopped=True):
+            if not c.is_running:
+                log.info("Removing %s..." % c.name)
+                c.remove(**options)
+
+    def create_container(self,
+                         one_off=False,
+                         insecure_registry=False,
+                         do_build=True,
+                         **override_options):
+        """
+        Create a container for this service. If the image doesn't exist, attempt to pull
+        it.
+        """
+        container_options = self._get_container_create_options(
+            override_options,
+            one_off=one_off)
+
+        if (do_build and
+                self.can_be_built() and
+                not self.client.images(name=self.full_name)):
+            self.build()
+
+        try:
+            return Container.create(self.client, **container_options)
+        except APIError as e:
+            if e.response.status_code == 404 and e.explanation and 'No such image' in str(e.explanation):
+                log.info('Pulling image %s...' % container_options['image'])
+                output = self.client.pull(
+                    container_options['image'],
+                    stream=True,
+                    insecure_registry=insecure_registry
+                )
+                stream_output(output, sys.stdout)
+                return Container.create(self.client, **container_options)
+            raise
+
+    def recreate_containers(self, insecure_registry=False, do_build=True, **override_options):
+        """
+        If a container for this service doesn't exist, create and start one. If there are
+        any, stop them, create+start new ones, and remove the old containers.
+        """
+        containers = self.containers(stopped=True)
+        if not containers:
+            log.info("Creating %s..." % self._next_container_name(containers))
+            container = self.create_container(
+                insecure_registry=insecure_registry,
+                do_build=do_build,
+                **override_options)
+            self.start_container(container)
+            return [(None, container)]
+        else:
+            tuples = []
+
+            for c in containers:
+                log.info("Recreating %s..." % c.name)
+                tuples.append(self.recreate_container(c, insecure_registry=insecure_registry, **override_options))
+
+            return tuples
+
+    def recreate_container(self, container, **override_options):
+        """Recreate a container. An intermediate container is created so that
+        the new container has the same name, while still supporting
+        `volumes-from` the original container.
+        """
+        try:
+            container.stop()
+        except APIError as e:
+            if (e.response.status_code == 500
+                    and e.explanation
+                    and 'no such process' in str(e.explanation)):
+                pass
+            else:
+                raise
+
+        intermediate_container = Container.create(
+            self.client,
+            image=container.image,
+            entrypoint=['/bin/echo'],
+            command=[],
+            detach=True,
+        )
+        intermediate_container.start(volumes_from=container.id)
+        intermediate_container.wait()
+        container.remove()
+
+        options = dict(override_options)
+        new_container = self.create_container(do_build=False, **options)
+        self.start_container(new_container, intermediate_container=intermediate_container)
+
+        intermediate_container.remove()
+
+        return (intermediate_container, new_container)
+
+    def start_container_if_stopped(self, container, **options):
+        if container.is_running:
+            return container
+        else:
+            log.info("Starting %s..." % container.name)
+            return self.start_container(container, **options)
+
+    def start_container(self, container, intermediate_container=None, **override_options):
+        options = dict(self.options, **override_options)
+        port_bindings = build_port_bindings(options.get('ports') or [])
+
+        volume_bindings = dict(
+            build_volume_binding(parse_volume_spec(volume))
+            for volume in options.get('volumes') or []
+            if ':' in volume)
+
+        privileged = options.get('privileged', False)
+        net = options.get('net', 'bridge')
+        dns = options.get('dns', None)
+        dns_search = options.get('dns_search', None)
+        cap_add = options.get('cap_add', None)
+        cap_drop = options.get('cap_drop', None)
+
+        restart = parse_restart_spec(options.get('restart', None))
+
+        container.start(
+            links=self._get_links(link_to_self=options.get('one_off', False)),
+            port_bindings=port_bindings,
+            binds=volume_bindings,
+            volumes_from=self._get_volumes_from(intermediate_container),
+            privileged=privileged,
+            network_mode=net,
+            dns=dns,
+            dns_search=dns_search,
+            restart_policy=restart,
+            cap_add=cap_add,
+            cap_drop=cap_drop,
+        )
+        return container
+
+    def start_or_create_containers(
+            self,
+            insecure_registry=False,
+            detach=False,
+            do_build=True):
+        containers = self.containers(stopped=True)
+
+        if not containers:
+            log.info("Creating %s..." % self._next_container_name(containers))
+            new_container = self.create_container(
+                insecure_registry=insecure_registry,
+                detach=detach,
+                do_build=do_build,
+            )
+            return [self.start_container(new_container)]
+        else:
+            return [self.start_container_if_stopped(c) for c in containers]
+
+    def get_linked_names(self):
+        return [s.name for (s, _) in self.links]
+
+    def _next_container_name(self, all_containers, one_off=False):
+        bits = [self.project, self.name]
+        if one_off:
+            bits.append('run')
+        return '_'.join(bits + [str(self._next_container_number(all_containers))])
+
+    def _next_container_number(self, all_containers):
+        numbers = [parse_name(c.name).number for c in all_containers]
+        return 1 if not numbers else max(numbers) + 1
+
+    def _get_links(self, link_to_self):
+        links = []
+        for service, link_name in self.links:
+            for container in service.containers():
+                links.append((container.name, link_name or service.name))
+                links.append((container.name, container.name))
+                links.append((container.name, container.name_without_project))
+        if link_to_self:
+            for container in self.containers():
+                links.append((container.name, self.name))
+                links.append((container.name, container.name))
+                links.append((container.name, container.name_without_project))
+        for external_link in self.external_links:
+            if ':' not in external_link:
+                link_name = external_link
+            else:
+                external_link, link_name = external_link.split(':')
+            links.append((external_link, link_name))
+        return links
+
+    def _get_volumes_from(self, intermediate_container=None):
+        volumes_from = []
+        for volume_source in self.volumes_from:
+            if isinstance(volume_source, Service):
+                containers = volume_source.containers(stopped=True)
+
+                if not containers:
+                    volumes_from.append(volume_source.create_container().id)
+                else:
+                    volumes_from.extend(map(attrgetter('id'), containers))
+
+            elif isinstance(volume_source, Container):
+                volumes_from.append(volume_source.id)
+
+        if intermediate_container:
+            volumes_from.append(intermediate_container.id)
+
+        return volumes_from
+
+    def _get_container_create_options(self, override_options, one_off=False):
+        container_options = dict(
+            (k, self.options[k])
+            for k in DOCKER_CONFIG_KEYS if k in self.options)
+        container_options.update(override_options)
+
+        container_options['name'] = self._next_container_name(
+            self.containers(stopped=True, one_off=one_off),
+            one_off)
+
+        # If a qualified hostname was given, split it into an
+        # unqualified hostname and a domainname unless domainname
+        # was also given explicitly. This matches the behavior of
+        # the official Docker CLI in that scenario.
+        if ('hostname' in container_options
+                and 'domainname' not in container_options
+                and '.' in container_options['hostname']):
+            parts = container_options['hostname'].partition('.')
+            container_options['hostname'] = parts[0]
+            container_options['domainname'] = parts[2]
+
+        if 'ports' in container_options or 'expose' in self.options:
+            ports = []
+            all_ports = container_options.get('ports', []) + self.options.get('expose', [])
+            for port in all_ports:
+                port = str(port)
+                if ':' in port:
+                    port = port.split(':')[-1]
+                if '/' in port:
+                    port = tuple(port.split('/'))
+                ports.append(port)
+            container_options['ports'] = ports
+
+        if 'volumes' in container_options:
+            container_options['volumes'] = dict(
+                (parse_volume_spec(v).internal, {})
+                for v in container_options['volumes'])
+
+        container_options['environment'] = merge_environment(container_options)
+
+        if self.can_be_built():
+            container_options['image'] = self.full_name
+        else:
+            container_options['image'] = self._get_image_name(container_options['image'])
+
+        # Delete options which are only used when starting
+        for key in DOCKER_START_KEYS:
+            container_options.pop(key, None)
+
+        return container_options
+
+    def _get_image_name(self, image):
+        repo, tag = parse_repository_tag(image)
+        if tag == "":
+            tag = "latest"
+        return '%s:%s' % (repo, tag)
+
+    def build(self, no_cache=False):
+        log.info('Building %s...' % self.name)
+
+        build_output = self.client.build(
+            self.options['build'],
+            tag=self.full_name,
+            stream=True,
+            rm=True,
+            nocache=no_cache,
+        )
+
+        try:
+            all_events = stream_output(build_output, sys.stdout)
+        except StreamOutputError, e:
+            raise BuildError(self, unicode(e))
+
+        image_id = None
+
+        for event in all_events:
+            if 'stream' in event:
+                match = re.search(r'Successfully built ([0-9a-f]+)', event.get('stream', ''))
+                if match:
+                    image_id = match.group(1)
+
+        if image_id is None:
+            raise BuildError(self, event if all_events else 'Unknown')
+
+        return image_id
+
+    def can_be_built(self):
+        return 'build' in self.options
+
+    @property
+    def full_name(self):
+        """
+        The tag to give to images built for this service.
+        """
+        return '%s_%s' % (self.project, self.name)
+
+    def can_be_scaled(self):
+        for port in self.options.get('ports', []):
+            if ':' in str(port):
+                return False
+        return True
+
+    def pull(self, insecure_registry=False):
+        if 'image' in self.options:
+            image_name = self._get_image_name(self.options['image'])
+            log.info('Pulling %s (%s)...' % (self.name, image_name))
+            self.client.pull(
+                image_name,
+                insecure_registry=insecure_registry
+            )
+
+
+NAME_RE = re.compile(r'^([^_]+)_([^_]+)_(run_)?(\d+)$')
+
+
+def is_valid_name(name, one_off=False):
+    match = NAME_RE.match(name)
+    if match is None:
+        return False
+    if one_off:
+        return match.group(3) == 'run_'
+    else:
+        return match.group(3) is None
+
+
+def parse_name(name):
+    match = NAME_RE.match(name)
+    (project, service_name, _, suffix) = match.groups()
+    return ServiceName(project, service_name, int(suffix))
+
+
+def parse_restart_spec(restart_config):
+    if not restart_config:
+        return None
+    parts = restart_config.split(':')
+    if len(parts) > 2:
+        raise ConfigError("Restart %s has incorrect format, should be "
+                          "mode[:max_retry]" % restart_config)
+    if len(parts) == 2:
+        name, max_retry_count = parts
+    else:
+        name, = parts
+        max_retry_count = 0
+
+    return {'Name': name, 'MaximumRetryCount': int(max_retry_count)}
+
+
+def parse_volume_spec(volume_config):
+    parts = volume_config.split(':')
+    if len(parts) > 3:
+        raise ConfigError("Volume %s has incorrect format, should be "
+                          "external:internal[:mode]" % volume_config)
+
+    if len(parts) == 1:
+        return VolumeSpec(None, parts[0], 'rw')
+
+    if len(parts) == 2:
+        parts.append('rw')
+
+    external, internal, mode = parts
+    if mode not in ('rw', 'ro'):
+        raise ConfigError("Volume %s has invalid mode (%s), should be "
+                          "one of: rw, ro." % (volume_config, mode))
+
+    return VolumeSpec(external, internal, mode)
+
+
+def parse_repository_tag(s):
+    if ":" not in s:
+        return s, ""
+    repo, tag = s.rsplit(":", 1)
+    if "/" in tag:
+        return s, ""
+    return repo, tag
+
+
+def build_volume_binding(volume_spec):
+    internal = {'bind': volume_spec.internal, 'ro': volume_spec.mode == 'ro'}
+    external = os.path.expanduser(volume_spec.external)
+    return os.path.abspath(os.path.expandvars(external)), internal
+
+
+def build_port_bindings(ports):
+    port_bindings = {}
+    for port in ports:
+        internal_port, external = split_port(port)
+        if internal_port in port_bindings:
+            port_bindings[internal_port].append(external)
+        else:
+            port_bindings[internal_port] = [external]
+    return port_bindings
+
+
+def split_port(port):
+    parts = str(port).split(':')
+    if not 1 <= len(parts) <= 3:
+        raise ConfigError('Invalid port "%s", should be '
+                          '[[remote_ip:]remote_port:]port[/protocol]' % port)
+
+    if len(parts) == 1:
+        internal_port, = parts
+        return internal_port, None
+    if len(parts) == 2:
+        external_port, internal_port = parts
+        return internal_port, external_port
+
+    external_ip, external_port, internal_port = parts
+    return internal_port, (external_ip, external_port or None)
+
+
+def merge_environment(options):
+    env = {}
+
+    if 'env_file' in options:
+        if isinstance(options['env_file'], list):
+            for f in options['env_file']:
+                env.update(env_vars_from_file(f))
+        else:
+            env.update(env_vars_from_file(options['env_file']))
+
+    if 'environment' in options:
+        if isinstance(options['environment'], list):
+            env.update(dict(split_env(e) for e in options['environment']))
+        else:
+            env.update(options['environment'])
+
+    return dict(resolve_env(k, v) for k, v in env.iteritems())
+
+
+def split_env(env):
+    if '=' in env:
+        return env.split('=', 1)
+    else:
+        return env, None
+
+
+def resolve_env(key, val):
+    if val is not None:
+        return key, val
+    elif key in os.environ:
+        return key, os.environ[key]
+    else:
+        return key, ''
+
+
+def env_vars_from_file(filename):
+    """
+    Read in a line delimited file of environment variables.
+    """
+    env = {}
+    for line in open(filename, 'r'):
+        line = line.strip()
+        if line and not line.startswith('#'):
+            k, v = split_env(line)
+            env[k] = v
+    return env