Docker Compose reference

Docker Compose are for developers who don't want to deal with the complexities of Kubernetes manifests. Okteto implements and extends the Compose Specification to make it easy to develop Docker Compose applications in Kubernetes.

Example

services:
  vote:
    build: vote
    scale: 2
    environment:
      - FLASK_ENV=development
    command: python app.py
    ports:
      - 8080:8080
    volumes:
      - ./vote:/src

  redis:
    image: redis
    ports:
      - 6379
    volumes:
      - redis:/data

volumes:
  redis:

The equivalent Kubernetes manifests would have more than 300 lines of yaml!

Schema reference

services ([object], optional)

Define the services that make up your Docker Compose application.

services:
  vote:
    build: vote
    scale: 2
    ports:
      - 8080:8080

  redis:
    image: redis
    ports:
      - 6379
    volumes:
      - redis:/data

Each service supports the fields in the Compose Specification. We summarize the most relevant ones below:

build ([string|object], optional)

Indicate how to build the image of this service when running okteto build or okteto deploy --build. The value is the path to the build context:

build: vote

It can also be an object with these fields:

• context: the build context. When the value supplied is a relative path, it is interpreted as relative to the location of the Docker Compose file (default: .)
• dockerfile: the path to the Dockerfile. It is a relative path to the build context (default: Dockerfile)
• target: build the specified stage as defined inside the Dockerfile. See the multi-stage build Docker official docs for details.
• args: add build arguments, which are environment variables accessible only during the build process. Build arguments with a value containing a $ sign are resolved to the environment variable value on the machine okteto is running on, which can be helpful for secret or machine-specific values.
• export_cache: image tag for exported cache when build.
• cache_from: list of images to import cache from.

build:
  context: .
  dockerfile: Dockerfile
  target: prod
  args:
    - ENV1=prod
    - ENV2=$VALUE

okteto deploy --build builds a new docker image, pushes it to the registry and redeploys your containers. By default, it builds the images using the Okteto Build Service. Set the variable BUILDKIT_HOST if you want to use your own BuildKit instance.

cap_add ([string], optional)

Add container capabilities. See man 7 capabilities for a full list.

cap_add:
  - ALL

cap_drop ([string], optional)

Drop container capabilities. See man 7 capabilities for a full list.

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN

command (string, optional)

Override the default command of the container image CMD.

command: --debug

command can also be a list of strings:

command: ["-p", "3000"]

depends_on ([string]|object, optional)

Specify the conditions that the declared services must meet in order for the service to start. The condition must be one of the following:

• service_started: Wait until the service is running.
• service_healthy: Wait for one of the ports of the dependent service to be available.
• service_completed_successfully: Wait until the dependent service has been successfully completed.

depends_on:
  app:
    condition: service_started
  db:
    condition: service_healthy
  initialization-svc:
    condition: service_completed_successfully

You can also express dependencies as a list of services. In this case it will be the same as setting the condition to service_started.

depends_on:
  - app
  - db
  - initialization-svc

entrypoint (string, optional)

Override the default entrypoint of the container image ENTRYPOINT.

entrypoint: yarn start

The entrypoint can also be a list of strings:

entrypoint: ["yarn", "start"]

env_file (string, optional)

Add environment variables from a file to the containers of a service. Environment variables declared in the environment section override these values. This also holds true if those values are empty or undefined.

env_file: .env

env_file also accepts a list of files:

env_file:
  - .env.frontend
  - .env.api

environment ([string], optional)

Add environment variables:

environment:
  DEV_MODE: yes
  DB_HOST: postgres://${DB_HOST:-db}:${DB_PASSWORD}@postgres:5432/postgres

healthcheck (object, optional)

healthcheck declares a check that's run to determine whether or not containers for a service are "healthy".

• start_period (duration): Time between the start of the container and the initiation of the healthcheck.
• interval (duration): Time between a healthcheck and a subsequent new try.
• timeout (duration): Number of seconds after which the healthcheck times out.
• retries (int): Number of retries before healthcheck fails.
• test (string): Defines the command that will be run to check the container's health. It can be either a string or a list. If it's a list, the first item must be either NONE, CMD or CMD-SHELL. If it's a string, it's equivalent to specifying CMD-SHELL followed by that string.
• http (object): Defines the path and port that has to be tested on the container to set the healthcheck as successful
• x-okteto-readiness (bool): Defines if the probe should be a readiness probe (default: true).
• x-okteto-liveness (bool): Defines if the probe should be a liveness probe (default: false).

healthcheck:
  interval: 10s
  timeout: 10m
  retries: 5
  start_period: 30s
  http:
    path: /
    port: 8080

Healthchecks can also test a command as follows:

healthcheck:
  interval: 10s
  timeout: 10m
  retries: 5
  start_period: 30s
  test: echo 'db.runCommand({serverStatus:1}).ok' | mongo admin -u $MONGO_INITDB_ROOT_USERNAME -p $MONGO_INITDB_ROOT_PASSWORD --quiet | grep 1

image (string, optional)

The container image of each service.

image: okteto/vote:compose

If build is defined, image is optional. Otherwise, it's required.

labels ([string], optional)

Specify labels for the service. They translates to Kubernetes annotations.

labels:
  app: sample

ports ([int], optional)

Ports exposed by each service. By default, they're only accessible from the cluster private network.

ports:
  - 8080

To make the port public, use the following notation:

ports:
  - 8080:8080

If you need to configure HTTPS routes, use endpoints instead of configuring an NGINX container in your Docker Compose file.

The following ports are never made public:

Protocol	Port
MySQL	3306
OracleDB	1521,1830
PostgreSQL	5432
SQL Server	1433,1434
MaxDB	7210
Neo4j	7473
ArangoDB	8529
Cassandra	7000,7001,9042
InfluxDB	8086
Elasticsearch	9200,9300
CouchDB	5984
MongoDB	27017,27018,27019,28017
Redis	6379
Riak	8087,8088
RethinkDB	828015,29015,28015
Solr	7574,8983
Golang debugger	2345
Node debugger	5858,9229
Java debugger	5005
Ruby debugger	1234
Python debugger	4444,5678

If you need make these ports public, you can use endpoints.

scale (int, optional)

Specify the number of containers running for each service (default: 1).

scale: 2

resources (object, optional)

Configure resource requests and limits.

resources:
  requests:
    cpu: 300m
    memory: 500Mi
  limits:
    cpu: 500m
    memory: 800Mi

Or with the docker-compose v3 configuration.

deploy: 
  resources:
    reservations:
      cpus: 500m
      memory: 800Mi
    limits:
      cpus: 300m
      memory: 500Mi      

restart (string, optional)

Defines the policy that the platform will apply on container termination.

• always/unless-stopped/any: The default restart policy. The policy always restarts the container until its removal.
• none/never/no: The policy does not restart a container under any circumstances.
• on-failure: The policy restarts a container if the exit code indicates an error.

deploy:
  restart_policy:
    condition: on-failure
    max_attempts: 3

If the restart policy is other than always, the service will be translated to a Kubernetes Job.

stop_grace_period (duration|int, optional)

Specify how long to wait when attempting to stop a container before sending SIGKILL. If no unit of time is given, the system will interpret the number in seconds.

stop_grace_period: 10s

volumes ([string], optional)

Define volumes accessible by the containers of a service at a given path.

volumes:
  - redis:/data

The volume redis must be defined in the volumes section.

The following notation is also accepted:

volumes:
  - /data

Finally, host volumes are also supported:

volumes:
  - .:/usr/app/src

Host volumes are added to your containers at deployment time. In addition, okteto up uses host volumes to infer the sync paths between your local filesystem and your remote development container.

By default, services mounting the same volume will be placed on the same node using Kubernetes's pod affinity. If you wish to disable this behavior, set the environment variable OKTETO_COMPOSE_VOLUME_AFFINITY_ENABLED to false when deploying. You can also optionally configure this variable from the Okteto UI to make it available to all development environments in your namespace.

working_dir (string, optional)

Override the default working directory of the container image WORKDIR.

working_dir: "/app/code"

x-node-selector (map[string]string, optional)

List of labels that the node must have to include the service containers on it.

x-node-selector:
  disktype: ssd

More information about Kubernetes node selectors is available here.

volumes ([object], optional)

List of volumes created by the Docker Compose file. Volumes are mounted on the containers of a given service by referring the volume from the volumes field of the service.

volumes:
  redis:
    driver_opts:
      size: 1Gi

Each volume has the following properties:

labels (string, optional)

Specify labels for the volume. They translates to Kubernetes annotations.

labels:
  app: redis

driver_opts.class (string, optional)

Specify the storage class of the volume.

driver_opts:
  class: standard

driver_opts.size (string, optional)

Specify the size of the volume. Defaults to 1Gi.

driver_opts:
  size: 1Gi

Environment variables

There are multiple parts of Docker Compose files that deal with environment variables in one sense or another. This section should help you find the information you need.

Environment variable substitution

It’s possible to use environment variables in your shell to populate values inside your Docker Compose file:

services:
  web:
    image: "app:${TAG}"

If you have multiple environment variables, you can substitute them by adding them to a file named .env.

The .env file

You can set default values for any environment variables referenced in your Docker Compose file in an environment file named .env. The .env file is placed at the same folder than the Docker Compose file.

For example:

$ cat .env
TAG=v1.5

$ cat docker-compose.yml
services:
   web:
      image: "app:${TAG}"

When you run okteto deploy the web container uses the image app:v1.5.

Values in the shell take precedence over those specified in the .env file.

extensions (object, optional)

Specifies a configuration that can be used in other services using anchors. Every top-level field starting with the prefix 'x-' will be interpreted as an extension.

x-function: &environment
  environment:
    DEV_MODE: yes
    DB_HOST: postgres://${DB_HOST:-db}:${DB_PASSWORD}@postgres:5432/postgres
services:
  app:
    <<: *environment
    image: okteto.dev/example

Okteto Variables

You can also use your Okteto Variables in your Docker Compose file.

For example, if your have an Okteto Variable named PASSWORD whose value is change-me!, the following Docker Compose file:

services:
  mysql:
    image: mysql
    environment:
      - MYSQL_ROOT_PASSWORD=${PASSWORD}

will use change-me! for the value of the MYSQL_ROOT_PASSWORD environment variable of the mysql service when you run okteto deploy.

Values in the shell and/or the .env file take precedence over those specified as Okteto Variables.

Okteto makes Docker Compose even more powerful!

Okteto extends the Compose Specification to make it even easier for you and your team to build cloud-native applications.

endpoints ([object], optional)

Endpoints expose HTTPS routes from outside the cluster to services within the cluster. Use this instead of having to run a NGINX proxy in your Docker Compose file.

endpoints:
  - path: /
    service: frontend
    port: 80
  - path: /api
    service: api
    port: 8080

The endpoint uses the name of the development environment to generate a URL with the following format: https://NAME-NAMESPACE.okteto.example.com.

Each endpoint has the following properties:

path (string, required)

The request path that will handle this route.

service (string, required)

The service that will receive the request.

port (int, required)

The port that will receive the request.

If more than one endpoint is needed, you can declare multiple endpoints by using a map with the name of the endpoint and its specification:

endpoints:
  landing:
    - path: /
      service: nginx
      port: 80
  web:
    - path: /
      service: frontend
      port: 80
    - path: /api
      service: api
      port: 8080

In this case, the URLs landing-NAMESPACE.okteto.example.com and web-NAMESPACE.okteto.example.com are created.

endpoints also accepts an extended notation to specify labels for each endpoint:

endpoints:
  labels:
    kubernetes.io/ingress.class: nginx
  rules:
    - path: /
      service: frontend
      port: 3000
    - path: /api
      service: backend
      port: 8080

update (annotation, optional)

You can set the update policy of a service by setting the annotation dev.okteto.com/update.

Depending on the kind of resource the acceptance values are different:

• rolling: Will deploy a service with zero downtime. Only allowed for deployments and stateful sets.
• recreate: Will wait until the current pod is deleted to start creating the new one. Only allowed on deployments.
• on-delete: Will wait until the current pod is deleted to start creating the new one. Only allowed on stateful sets.

services:
  deployment:
    image: python:alpine
    labels:
      "dev.okteto.com/update": rolling
    entrypoint: python -m http.server 8080
    ports:
      - 8080:8080
  sfs:
    image: python:alpine
    labels:
      "dev.okteto.com/update": on-delete
    entrypoint: python -m http.server 8080
    ports:
      - 8080:8080
    volumes:
    - /usr/src

Remember that if you are on a docker-compose file the labels are translated into kubernetes annotations.