Docker service configuration
This documentation set has been merged with the Maestro Version 2 documentation and is officially deprecated. These pages will be redirected to their equivalents in that doc set within the next few weeks.
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:
- Defining build and deploy commands
- Specifying a central logging folder
- Setting port definitions for your containers
- Mount volumes into your containers
- Set dependencies between your containers
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.
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.
As you can see above, we are running a web and api service with different configurations. They are running on MySQL and Redis databases.
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.
|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||One of the values: default, none or a hash containing at least one of type, endpoint, protocol, accept or timeout.|
|image|| The image you would typically run
|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
|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
|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)|
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:
glusterfs. For example:
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:
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
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.