<commit_before>---
title: Services Configuration
layout: page
weight: 56
tags:
  - docker
  - jet
  - configuration
  - services
categories:
  - docker
---

* include a table of contents
{:toc}

By default, services are expected to be in one of the following 5 files:

* `jet-services.yml`
* `jet-services.json`
* `codeship-services.yml`
* `codeship-services.json`
* `docker-compose.yml`

_Jet_ will look for a services file in this order. If you are running _Jet_ locally you can override the filename with the `--services-path` flag. Both YAML and JSON formats are accepted.

The definition of docker services is exactly the same as for Docker Compose's [docker-compose.yml definition](https://docs.docker.com/compose/yml/), with a few omissions and optional changes.

## Unavailable features

The following directives were just added to docker-compose very recently, and are expected to be implemented but have not been implemented yet:

* `extends`
* `labels`

## Linking to the host

All linking to the host is not allowed. This means the following directives are excluded:

* `external_links`
* `ports`
* `stdin_open`

In addition the behavior of `volumes` has been changed to only allow _CONTAINER_ specifications and ignore any _HOST:CONTAINER_ specifications present.

## Builds

The `build` directive is extended. You can still specify a build in the same way as in docker-compose, just using the directory. However, you can also use our own format:

```yml
app:
  build:
    image: codeship/foo
    path: testpath
    dockerfile_path: Dockerfile.foo
  image: codeship/foo
  configure:
    service: codeship/buildfoo
    command: make compile
```

Let's walk through this:

* `image` specifies the output image name, as opposed to generating one by default.
* `path` allows you specify a `custom_directory` to use as the context for building the Docker container. _Note_, that the _Dockerfile_ is searched for relative to that directory. If you don't specify this option, it will default to the directory of the services file.
* `dockerfile_path` allows you to specify a file name as opposed to a directory name. This is useful for having multiple _Dockerfile_'s in the same directory.
* `configure` is optional if using this format. This does the following:
  * Bring up the named service, which must be also described in the services file.
  * Link your working directory into this service and make this the working directory within the service.
  * Run the specified command.

`configure` is useful if steps must be done prior to running `docker build`. For example, when developing _Jet_, we run it inside a Docker container. _Jet_ is written using go, and go allows you to produce a small compiled binary (in this case about 7MB). We need this binary to be available before we can run `docker build`. Otherwise, we would have to have a container that had Go available and compile within it, which results in a 500+MB container. The above example is exactly how we do this.

You must use one of the two formats, either Docker Compose's format, or our format. You can intermix these formats within a given file.

## Environment Variables

The standard `environment` and `env_file` directives are supported. Additionally, we support encrypted environment variables
with `encrypted_environment` and `encrypted_env_file` directives. These are the same format, except they expect encrypted variables.

See the description of the [encryption commands]({{ site.baseurl }}{% post_url docker/jet/2015-05-25-cli %}#encryption-commands) for more information and how to use this.

## Docker inside Docker

The boolean directive `add_docker` is available. If specified for a service, it will

* add the environment variables `DOCKER_HOST`, `DOCKER_TLS_VERIFY` and `DOCKER_CERT_PATH` from the host.
* if `DOCKER_CERT_PATH` is set, it will mount the certificate directory through to the container.

See [add_docker](https://github.com/codeship/codeship-tool-examples/tree/master/14.add_docker) for an example using [Docker-in-Docker](https://registry.hub.docker.com/u/jpetazzo/dind).

## Using the Docker cache

We allow the use of the previous Docker build cache during future builds. To enable this for your builds you must add the `cached` declaration to you service definition:

```yml
app:
  build:
    image: codeship/foo
    path: testpath
    dockerfile_path: Dockerfile.foo
  cached: true
```

You must also ensure that the generated image is pushed to a repository via a push step. With this in place we will pull down a special cache tag (codeship-cache-$BRANCH) from your registry and allow the Docker build to use this image cache. During your push, we'll also update the cache tag with the updated Docker image. 

This entire process should be seamless. You'll be notified of pull errors with the cache image should we be unable to pull or push due to connectivity or authentication issues, however there is no need to pre-populate an image cache.

For more information, take a look at the our [caching example](https://github.com/codeship/codeship-tool-examples/tree/master/17.caching). Be sure to check out our [Caching Tutorial]({{ site.baseurl }}{% post_url docker/tutorials/2015-09-07-caching %})  for a more detailed look at how to speed up your builds.

## Other Notes

* `link` containers will be newly created for each step.
* `volumes_from` containers will be created exactly once for all services.
<commit_msg>Move the image only example to its own service<commit_after>---
title: Services Configuration
layout: page
weight: 56
tags:
  - docker
  - jet
  - configuration
  - services
categories:
  - docker
---

* include a table of contents
{:toc}

By default, services are expected to be in one of the following 5 files:

* `jet-services.yml`
* `jet-services.json`
* `codeship-services.yml`
* `codeship-services.json`
* `docker-compose.yml`

_Jet_ will look for a services file in this order. If you are running _Jet_ locally you can override the filename with the `--services-path` flag. Both YAML and JSON formats are accepted.

The definition of docker services is exactly the same as for Docker Compose's [docker-compose.yml definition](https://docs.docker.com/compose/yml/), with a few omissions and optional changes.

## Unavailable features

The following directives were just added to docker-compose very recently, and are expected to be implemented but have not been implemented yet:

* `extends`
* `labels`

## Linking to the host

All linking to the host is not allowed. This means the following directives are excluded:

* `external_links`
* `ports`
* `stdin_open`

In addition the behavior of `volumes` has been changed to only allow _CONTAINER_ specifications and ignore any _HOST:CONTAINER_ specifications present.

## Builds

The `build` directive is extended. You can still specify a build in the same way as in docker-compose, just using the directory. However, you can also use our own format:

```yaml
app:
  build:
    image: codeship/foo
    path: testpath
    dockerfile_path: Dockerfile.foo
  configure:
    service: codeship/buildfoo
    command: make compile
deploy:
  image: codeship/heroku-deployment
```

Let's walk through this:

* `image` specifies the output image name, as opposed to generating one by default.
* `path` allows you specify a `custom_directory` to use as the context for building the Docker container. _Note_, that the _Dockerfile_ is searched for relative to that directory. If you don't specify this option, it will default to the directory of the services file.
* `dockerfile_path` allows you to specify a file name as opposed to a directory name. This is useful for having multiple _Dockerfile_'s in the same directory.
* `configure` is optional if using this format. This does the following:
  * Bring up the named service, which must be also described in the services file.
  * Link your working directory into this service and make this the working directory within the service.
  * Run the specified command.

`configure` is useful if steps must be done prior to running `docker build`. For example, when developing _Jet_, we run it inside a Docker container. _Jet_ is written using go, and go allows you to produce a small compiled binary (in this case about 7MB). We need this binary to be available before we can run `docker build`. Otherwise, we would have to have a container that had Go available and compile within it, which results in a 500+MB container. The above example is exactly how we do this.

You must use one of the two formats, either Docker Compose's format, or our format. You can intermix these formats within a given file.

## Environment Variables

The standard `environment` and `env_file` directives are supported. Additionally, we support encrypted environment variables
with `encrypted_environment` and `encrypted_env_file` directives. These are the same format, except they expect encrypted variables.

See the description of the [encryption commands]({{ site.baseurl }}{% post_url docker/jet/2015-05-25-cli %}#encryption-commands) for more information and how to use this.

## Docker inside Docker

The boolean directive `add_docker` is available. If specified for a service, it will

* add the environment variables `DOCKER_HOST`, `DOCKER_TLS_VERIFY` and `DOCKER_CERT_PATH` from the host.
* if `DOCKER_CERT_PATH` is set, it will mount the certificate directory through to the container.

See [add_docker](https://github.com/codeship/codeship-tool-examples/tree/master/14.add_docker) for an example using [Docker-in-Docker](https://registry.hub.docker.com/u/jpetazzo/dind).

## Using the Docker cache

We allow the use of the previous Docker build cache during future builds. To enable this for your builds you must add the `cached` declaration to you service definition:

```yml
app:
  build:
    image: codeship/foo
    path: testpath
    dockerfile_path: Dockerfile.foo
  cached: true
```

You must also ensure that the generated image is pushed to a repository via a push step. With this in place we will pull down a special cache tag (codeship-cache-$BRANCH) from your registry and allow the Docker build to use this image cache. During your push, we'll also update the cache tag with the updated Docker image.

This entire process should be seamless. You'll be notified of pull errors with the cache image should we be unable to pull or push due to connectivity or authentication issues, however there is no need to pre-populate an image cache.

For more information, take a look at the our [caching example](https://github.com/codeship/codeship-tool-examples/tree/master/17.caching). Be sure to check out our [Caching Tutorial]({{ site.baseurl }}{% post_url docker/tutorials/2015-09-07-caching %})  for a more detailed look at how to speed up your builds.

## Other Notes

* `link` containers will be newly created for each step.
* `volumes_from` containers will be created exactly once for all services.

{'fraction_non_alphanumeric': 0.06664835667856817, 'fraction_numerical': 0.004943696786597089, 'mean_word_length': 4.360157016683022, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4721799', 'n_tokens_mistral': 3049, 'n_tokens_neox': 2851, 'n_words': 1503}