Compose File Reference

The Compose file is a YAML file defining services, networks and volumes. The default path for a Compose file is ./docker-compose.yml.

A service definition contains configuration which will be applied to each container started for that service, much like passing command-line parameters to hyper run. Likewise, network and volume definitions are analogous to hyper network create and hyper volume create.

As with hyper run, options specified in the Docker Image(e.g., CMD, EXPOSE, VOLUME, ENV) are respected by default - you don’t need to specify them again in docker-compose.yml.

You can use environment variables in configuration values with a Bash-like ${VARIABLE} syntax - see variable substitution for full details.

Service configuration reference

Note: Hyper compose only supports two versions of the Compose file format – version 1 (the legacy format, which does not support volumes or networks) and version 2.

command

Override the default command.

command: bundle exec thin -p 3000

The command can also be a list:

command: [bundle, exec, thin, -p, 3000]

container_name

Specify a custom container name, rather than a generated default name.

container_name: my-web-container

Because Hyper container names must be unique, you cannot scale a service beyond 1 container if you have specified a custom name. Attempting to do so results in an error.

depends_on

Express dependency between services, which has two effects:

• compose up will start services in dependency order. In the following example, db and redis will be started before web.

• compose up SERVICE will automatically include SERVICE’s dependencies. In the following example, hyper compose up web will also create and start db and redis.

  Simple example:

  version: '2'
  services:
  web:
    image: wordpress
    depends_on:
      - db
  db:
    image: mysql

Note: depends_on will not wait for db and redis to be “ready” before starting web - only until they have been started. If you need to wait for a service to be ready, see Controlling startup order for more on this problem and strategies for solving it.

entrypoint

Override the default entrypoint.

entrypoint: /code/entrypoint.sh

The entrypoint can also be a list:

entrypoint:
    - php
    - -d
    - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
    - -d
    - memory_limit=-1
    - vendor/bin/phpunit

env_file

Add environment variables from a file. Only accept a list. If you have specified a Compose file with compose -f FILE, paths in env_file are relative to the directory that file is in. Environment variables specified in environment override these values.

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/secrets.env

Compose expects each line in an env file to be in VAR=VAL format. Lines beginning with # (i.e. comments) are ignored, as are blank lines.

# Set Rails/Rack environment
RACK_ENV=development

environment

Add environment variables. You can use either an array or a dictionary. Any boolean values; true, false, yes no, need to be enclosed in quotes to ensure they are not converted to True or False by the YML parser. Environment variables with only a key are resolved to their values on the machine Compose is running on, which can be helpful for secret or host-specific values.

environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:
environment:
  - RACK_ENV=development
  - SHOW=true
  - SESSION_SECRET

extends

Extend another service, in the current file or another, optionally overriding configuration. You can use extends on any service together with other configuration keys. The extends value must be a dictionary defined with a required service and an optional file key.

extends:
  file: common.yml
  service: webapp

The service the name of the service being extended, for example web or database. The file is the location of a Compose configuration file defining that service. If you omit the file Compose looks for the service configuration in the current file. The file value can be an absolute or relative path. If you specify a relative path, Compose treats it as relative to the location of the current file. You can extend a service that itself extends another. You can extend indefinitely. Compose does not support circular references and compose returns an error if it encounters one.

external_links

Link to containers started outside this docker-compose.yml or even outside of Compose, especially for containers that provide shared or common services. external_links follow semantics similar to links when specifying both the container name and the link alias (CONTAINER:ALIAS).

external_links:
 - redis_1
 - project_db_1:mysql
 - project_db_1:postgresql

Note: If you’re using the version 2 file format, the externally-created containers must be connected to at least one of the same networks as the service which is linking to them.

image

Specify the image to start the container from. Can either be a repository/tag or a partial image ID.

image: redis
image: ubuntu:14.04
image: tutum/influxdb
image: example-registry.com:4000/postgresql
image: a4bc65fd

If the image does not exist, Compose attempts to pull it, unless you have also specified build, in which case it builds it using the specified options and tags it with the specified tag.

labels

Add metadata to containers using Hyper labels. You can use either an array or a dictionary. It’s recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.

labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"

links

Link to containers in another service. Either specify both the service name and a link alias (SERVICE:ALIAS), or just the service name.

web:
  links:
   - db
   - db:database
   - redis

Containers for the linked service will be reachable at a hostname identical to the alias, or the service name if no alias was specified. Links also express dependency between services in the same way as depends_on, so they determine the order of service startup.

volumes

Mount paths or named volumes. For version 2 files, named volumes can be specified with the top-level volumes key, a public http/https source file, or a public git repository. When using version 1, the Hyper will create the named volume automatically if it doesn’t exist.

volumes:
  # Just specify a path and let the Engine create a volume
  - /var/lib/mysql
  # Named volume, datavolume is volume name
  - datavolume:/var/lib/my
  # Named volume, https source
  - https://raw.githubusercontent.com/msanand/docker-workflow/master/node/Dockerfile:/data/Dockerfile
  # Named volume, git repository
  - https://github.com/hyperhq/hypercli.git:/data/hypercli

Note: You can not specify local directory or files to init the volume like docker compose.

fip

Attach an allocated floating IP to a (running) container, each container can have only one floating IP. It will only accept a single string:

fip: 211.98.26.102

The reserved keyword auto tries to use free (existing) FIPs, before allocating more.

fip: auto

Note: the auto keyword only works with Hyper CLI.

size

The size for each container, it will only accept a single string. Available size is s1, s2, s3, s4, m1, m2, m3, l1, l2 and l3. For more details and price, you can refer the doc.

size: s4

noauto_volume

This option tells Hyper service not to create new volumes for VOLUME sections in the container image. If not specified, compose will automatically create volumes for each VOLUME section in the container image.

noauto_volume: true

security_groups

This option tells compose to add security groups to the container. A security group acts as a virtual firewall that controls the traffic for one or more containers.

security_groups:
  - sg-test-1

Hyper compose vs Docker compose

	Docker	Hyper	Note
build	x	-
cap_add	x	-	Add container capabilities.
cap_drop	x	-	Drop container capabilities.
command	x	x	Override the default command.
cgroup_parent	x	-	Specify an optional parent cgroup for the container.
container_name	x	x	Specify a custom container name, rather than a generated default name.
devices	x	-	List of device mappings.
depends_on	x	x	Express dependency between services.
dns	x	-	Custom DNS servers. Can be a single value or a list.
dns_search	x	-	Custom DNS search domains. Can be a single value or a list.
tmpfs	x	-	Mount a temporary file system inside the container.
entrypoint	x	x	Override the default entrypoint.
env_file	x	x	Add environment variables from a file.
environment	x	x	Add environment variables.
expose	x	x	Expose ports without publishing them to the host machine. (support later)
extends	x	x	Extend another service, in the current file or another, optionally overriding configuration.
external_links	x	x	Link to containers started outside this docker-compose.yml or even outside of Compose
extra_hosts	x	-	Add hostname mappings.
image	x	x	Specify the image to start the container from.
labels	x	x	Add metadata to containers using Docker labels.
links	x	x	Link to containers in another service.
logging	x	-	Logging configuration for the service.
log_driver	x	-	Specify a log driver.
log_opt	x	-	Specify logging options as key-value pairs.
net	x	-	[v1 only]network mode
network_mode	x	-	[v2 only]network mode
networks	x	-	[v2 only]Networks to join.
aliases	x	-	Aliases (alternative hostnames) for this service on the network.
ipv4_address	x	-	Specify a static IP address for containers for this service when joining the network.
ipv6_address	x	-	Specify a static IP address for containers for this service when joining the network.
pid	x	-	Sets the PID mode to the host PID mode.
ports	x	x	Expose ports.
security_opt	x	-	Override the default labeling scheme for each container.
stop_signal	x	x	Sets an alternative signal to stop the container.
ulimits	x	-	Override the default ulimits for a container.
volumes	x	x	Mount paths or named volumes.
volume_driver	x	-
volume_from	x	-	Mount all of the volumes from another service or container
cpu_shares	x	-	cpu_shares: 73
cpu_quota	x	-	cpu_quota: 50000
cpuset	x	-	cpuset: 0,1
domainname	x	x	domainname: foo.com
hostname	x	x	hostname: boo
ipc	x	-
mac_address	x	-	mac_address: 02:42:ac:11:65:43
mem_limit	x	-
memswap_limit	x	-
privileged	x	-
read_only	x	-
restart	x	x	restart: always
shm_size	x	-
stdin_open	x	x
tty	x	x
user	x	-
working_dir	x	x
size	-	x	instance size of Hyper container
fip	-	x	floating IP
security_groups	-	x	Security Groups
noauto_volume	-	x	Do not auto create volume
networks	x	-