sidecar-buildpacks.html.md.erb

---
title: Sidecar Buildpacks
Buildpacks owner: Buildpacks
---

This topic describes how buildpacks deploy sidecar processes alongside an app.

## <a id='overview'></a> Overview

Sidecar processes are additional dependent processes that are run in the same container as the main app process. For more information, see [How to Push an App to Cloud Foundry with Sidecars](https://www.cloudfoundry.org/blog/how-to-push-an-app-to-cloud-foundry-with-sidecars/).


## <a id='specify-sidecars'></a> How Buildpacks Specify Sidecar Processes

A buildpack can specify sidecar processes by writing a `launch.yml` at the root of its `deps` directory during the `supply` phase.  This `deps` directory is a combination of the `DEPS_DIR` and `DEP_IDX` values. For more information about how these two values are passed to the buildpack interface, see [How Buildpacks Work](understand-buildpacks.html).

The following defines the relevant fields of the `launch.yml` in more detail:

* `type`: A key that is mapped to a individual command.
  <p class='note'><strong>Note:</strong> It is possible for multiple buildpacks to write their own <code>launch.yml</code> files. If two of these files have the same <code>type</code> keys, the <code>launch.yml</code> written last overwrites the previous commands of the same <code>type</code>.</p>

* `command`: The command to be run in the container. Container health is dependent on this command, and the container fails when the command is no longer running.

* `limits`: Resource limits to be placed on the sidecar process.

* `memory`: The memory limit in MB. If you are using the sidecar buildpack with a Java app, you must configure this field to allocate memory to the sidecar. If you do not, the Java buildpack allocates all of the available memory to the app.

* `platforms`: A key specifying the data that should be read by a platform. For example, Cloud Foundry only reads data under the `cloudfoundry` key.

* `sidecar_for`: A list of `types` that the `command` is a sidecar process for.
  <p class='note'><strong>Note:</strong> Each <code>type</code> requires a health check, the <code>command</code> cannot run until each health check is passed. The more <code>type</code>s that are listed, the more health checks are required. If any health check fails, the <code>command</code> does not run.</p>

See the example `launch.yml` below:

```
---
processes:
- type: "PROCESS-NAME"
  command: "COMMAND"
  limits:
    memory: 10
  platforms:
    cloudfoundry:
      sidecar_for: [ "TYPE-1", "TYPE-2", "TYPE-3"]
```

Where:

* `PROCESS-NAME` is the command that is mapped to the `type` field.

* `COMMAND` is the command that is mapped to the `command` field. For example, `./binary` or `java -jar java-file.jar`.

* `TYPE-1`, `TYPE-2` and `TYPE-3` are the `type`s that the `command` is a sidecar process for.

### <a id='example'></a> Example Buildpack

This buildpack functions as a supply buildpack, or the non-final buildpack in a multi-buildpack build. Its only purpose is to write the `launch.yml` file to the buildpack's `deps` directory.

For the full sidecar buildpack described below, see the [example-sidecar-buildpack](https://github.com/cloudfoundry/example-sidecar-buildpack/) repository on GitHub.

The `example-sidecar-buildpack` has the following directory structure:

```
bin/
bin/supply
manifest.yml
VERSION
```

The `supply` script writes a `launch.yml` file to a specific location, `bin/supply`, as in the example below:

```
#!/bin/bash

set -euo pipefail

BUILD_DIR=$1
CACHE_DIR=$2
DEPS_DIR=$3
DEPS_IDX=$4

LAUNCH_CONTENTS='---
processes:
- type: "sidecar_process"
  command: "while true; do echo hello from a sidecar process; sleep 10; done"
  platforms:
    cloudfoundry:
      sidecar_for: [ "web"]
'

echo "-----> Running sidecar supply"

export BUILDPACK_DIR=`dirname $(readlink -f ${BASH_SOURCE%/*})`

pushd "$BUILDPACK_DIR"
  echo "$LAUNCH_CONTENTS" > "$DEPS_DIR"/"$DEPS_IDX"/launch.yml
popd

```