Docker service configuration

What is service configuration?

Service configuration allows you to be more explicit about your Docker services and control settings that are not usually available through the user interface or Cloud 66 toolbelt. These settings describe the setup of your services, and these are just some examples of the service configurations you can make:

How do I specify service configurations?

While you’re building your stack, service configurations are available on the Advanced tab. Once your stack has been built, you can find this configuration under Configure services in the right menu of your stack page. This form takes YAML input.

Service configuration examples

Example 1: Single service with MySQL database

In this example, we’ll be running a service called web, which is pulled from a Quay repository and requires a MySQL database.

    command: rackup -p 3000             
    build_command: rake db:schema:load
    deploy_command: rake db:migrate
    log_folder: /usr/src/app/log
    ports: ["3000:80:443"]        
  - "mysql"                              

As you can see above, the web service is based on a Quay image and requires the rackup -p 3000 startup command. It has both a build and a deploy command and specifies a logging folder. Finally, the container is set to listen on port 3000, and uses external ports 80 and 443.

Example 2: Multiple services and databases

In this example, we’ll be running two services - one for web and the other for an api, as well as MySQL and Redis databases. You can define as many services as you need. The first time you build your stack, those services will be started on the first server you build but you can use the UI, toolbelt or the API to move them around.

    git_branch: test   
    command: rackup -p 3000               
    build_command: rake db:migrate        
    deploy_command: rake db:migrate       
    log_folder: /usr/src/app/log          
    ports: ["3000:80:443", "4000"]        
    volumes: ["/tmp:/tmp/mnt_folder"]     
    health: default
    command: node test.js                 
    ports: ["1337:8080"]                  
    requires: ["web"]                     
  - "mysql"                               
  - "redis"                               

As you can see above, we are running a web and api service with different configurations. They are running on MySQL and Redis databases.

Service configurations

Below is a table of the available configurations for a given service with a brief description. For more detailed information about an option, click the link provided.

Option Description
build_command Specifies the command you would like to run during stack build.
build_root Specifies the directory of your repository in which you wish to run your Docker build.
command Specifies the command used to start your container.
constraints Specifies container amount or resource constraints for a service across the cluster.
deploy_command Specifies the command you would like to run during stack deploy (runs once per service).
dns_behaviour Specifies the dns behaviour for this service. One of the values: versioned, non-versioned. Default value is versioned
dockerfile_path Specifies the location of the Dockerfile to be used for building this service, eg. docker/Dockerfile.
tags Arbitrary tags for services
git_url The Git repository URL your Docker image will be built with.
git_branch The Git repository branch your Docker image will be based on.
use_habitus Use Habitus build workflow
use_habitus_step The Habitus step to use for the build.
health (CSv1) One of the values: default, none or a hash containing at least one of type, endpoint, protocol, accept or timeout.
health (CSv2) One of the values: default, none or a hash.
image The image you would typically run docker pull from.
load_balancing Specifies the load balancing method for this service. Accepted values are: roundrobin, sticky, closest. Default value is roundrobin
log_folder Folder your services logs to, mounted to /var/log/containers/service on the host filesystem.
ports The ports that are running within the container, as well as their corresponding external ports.
privileged (default: false) Boolean value to indicate whether the container should be run with extended privileges.
pre_start_signal This is a signal that is sent to the existing running containers of the service before the new service containers are started during deployment.
pre_stop_sequence This is a stop sequence that is executed on your running containers before they are shut down.
requires Array of other defined service names that should be started before this service during build and deployment.
restart_on_deploy (default: true) Boolean value to indicate whether the containers of this service should be restarted during deployment.
stop_grace Duration between the Docker TERM and KILL signals when Docker stop is run and a container is stopped.
traffic_matches The automatically configured traffic names in your Nginx config that will route traffic to these containers based on request DNS name. Allows microservices on the same port routes by subdomain for instance.
volumes The volumes that are mounted from your host into your container. Note:it must be absolute path.
work_dir Specifies the working directory in your image for any command to be run.
pre_stop_command This hook is called immediately before a container is terminated. Note: Only applies to container version 2 stacks (Kubernetes)
post_start_command This hook executes immediately after a container is created. Note: Only applies to container version 2 stacks (Kubernetes)

Database configurations

You can specify any required databases in the service configuration. As databases are fairly static components that rarely change without a migration, they aren’t run in containers. This avoids the complexity and overhead of running databases in a container, and allows Cloud 66 to perform replication and backups as normal. These databases will be deployed and configured automatically, and their addresses and access credentials will be made available to the containers across the stack with environment variables.

The allowed database values are: postgresql, mysql, redis, mongodb, elasticsearch , rabbitmq and glusterfs. For example:

    - mysql
    - elasticsearch

Environment variables

Any environment variable defined in your stack will be made available within your service container. You can also define new environment variable for a service or reference an environment variable in other stacks or services using the following syntax:

            # Setting an environment variable
            ENV_NAME1: VALUE

            # Referencing a stack-wide variable
            ENV_NAME2: _env(STACK_ENV_VAR_NAME)

            # Referencing a stack-wide variable (with default fall-back)
            ENV_NAME3: _env(STACK_ENV_VAR_NAME:Default)

            # Referencing a service's variable

            # Referencing a service's variable (with default fall-back)

            # Referencing another stack's variable

            # Referencing another stack's variable (with default fall-back)
            ENV_NAME7: _env(STACK[STACK_UID].ENV_VAR_NAME:Default)

            # Referencing another stacks' service variable

            # Referencing another stacks' service variable (with default fall-back)

In above example, all defined environment variables except ENV_NAME1 are referenced to other environment variables. You can specify a default value for referenced environment variables that will be set if there is no suitable link value (such as ENV_NAME3).

In addition to this, you can pass environment variables into your Dockerfile during your build process (if using BuildGrid) with the $VARIABLE syntax, which will be populated with environment variable(s) set on the stack.