# Tilt Documentation
# Source: https://docs.tilt.dev/docker_compose.html
# Path: docker_compose.html

  * [ Getting Started ](/index.html) [ Getting Started ](/docs_nav_gettingstarted.html)
  * [ Guides ](/tiltfile_authoring.html) [ Guides ](/docs_nav_guides.html)
  * [ Tiltfile & CLI ](/api.html) [ Tiltfile & CLI ](/docs_nav_reference.html)
  * [ Tilt API ](https://api.tilt.dev) [ Tilt API ](https://api.tilt.dev)

Tiltfile

    

  * [ Writing Your First Tiltfile ](/tiltfile_authoring.html)
  * [ Tiltfile Concepts ](/tiltfile_concepts.html)
  * [ Per user Config ](/tiltfile_config.html)
  * [ Many Tiltfiles and Many Repos ](/multiple_repos.html)
  * [ Debugging File Changes ](/file_changes.html)
  * [ Resource Dependencies ](/resource_dependencies.html)
  * [ Manual Update Control ](/manual_update_control.html)
  * [ Disabling Resources new ](/disable_resources.html)

Migrating Existing Projects

    

  * [ Plain Old Static HTML ](/example_static_html.html)
  * [ Go ](/example_go.html)
  * [ Python ](/example_python.html)
  * [ NodeJS ](/example_nodejs.html)
  * [ Java ](/example_java.html)
  * [ Bazel ](/example_bazel.html)
  * [ C# ](/example_csharp.html)

Building Images

    

  * [ Getting Started with Image Builds ](/dependent_images.html)
  * [ Setting up any Image Registry ](/personal_registry.html)
  * [ Custom Image Builders ](/custom_build.html)
  * [ Bazel ](/integrating_bazel_with_tilt.html)
  * [ Skaffold ](/skaffold.html)

Kubernetes Resources

    

  * [ Modifying YAML for Dev new ](/templating.html)
  * [ Installing YAML with Helm ](/helm.html)
  * [ Port Forwards ](/accessing_resource_endpoints.html)
  * [ Custom Resource Definitions ](/custom_resource.html)
  * [ Connecting Debuggers ](/debuggers_python.html)

More Resource Types

    

  * [ Local Commands, Servers, and Tests ](/local_resource.html)
  * [ Docker Compose ](/docker_compose.html)

Live Update

    

  * [ Technical Specifications ](/live_update_reference.html)

Continuous Integration (CI)

    

  * [ Overview ](/ci.html)

Extending Tilt

    

  * [ Custom Buttons ](/buttons.html)
  * [ Tiltfile Extensions ](/extensions.html)
  * [ Contribute Extensions ](/contribute_extension.html)

Tilt with Your Team

    

  * [ Onboarding Checklist ](/onboarding_checklist.html)
  * [ Sharing Snapshots ](/snapshots.html)

#  Setting Up Docker Compose

[Docker Compose](https://docs.docker.com/compose/) helps you define
microservice apps that run in multiple containers.

Most Tilt documentation uses Kubernetes to run multiple containers. But
thereâs also a strong subset of Tilt users who use Docker Compose as their
container runtime!

In this guide, weâll show you how to connect Docker Compose to a Tilt dev
environment. This lets you:

  * Organize each Docker Compose service from the Tilt dashboard.

  * Control when and how each service runs.

  * Add live updates in-place for each service.

If youâd like to skip straight to the example code, visit this repo:

[tilt-example-docker-compose](https://github.com/tilt-dev/tilt-example-docker-
compose)

The repo contains a complete sample app, a Tiltfile, and a test that uses
`tilt ci` to make sure the app runs successfully.

## Getting Started

Create a Tiltfile in the root of your repo:

    
    
    # point Tilt at the existing docker-compose configuration.
    docker_compose("./docker-compose.yml")
    

Thatâs it! Then run:

    
    
    tilt up
    

Tilt will pick up your Docker Compose file and start running your services.

Be aware of one important difference between `tilt up` and `docker-compose
up`: Tilt will leave your services up when it exits. To turn the services
down, run:

    
    
    tilt down
    

## Using Tiltâs `docker_build`

Tilt automatically uses your [`build`
configuration](https://docs.docker.com/compose/compose-file/#build) from
Docker Compose. You can also use the `docker_build` function to use Tiltâs
updating optimizations. Tilt will find the image name in your `docker-
compose.yml`, and use its own updating strategy instead of the one in the
`docker-compose.yml` file.

Letâs look at a simple example app that runs Redis and a NodeJS-based server
with Docker Compose. Weâll use the same example as in [this blog
post](https://codewithhugo.com/setting-up-express-and-redis-with-docker-
compose/) with [this Git repo](https://github.com/tilt-dev/tilt-example-
docker-compose).

First, we create a `Dockerfile` that sets up a NodeJS environment, adds the
NodeJS dependencies, then adds the source code.

    
    
    FROM node:9-alpine
    WORKDIR /var/www/app
    ADD package.json .
    RUN npm install
    ADD . .
    

Next, we put an image name in our `docker-compose.yml` file. Weâre not going
to be pushing this image to a remote registry, so any image name will do. We
use `tilt.dev/express-redis-app`.

    
    
    version: "3.9"
    services:
      redis:
        image: redis
        container_name: cache
        expose:
          - 6379
      app:
        image: tilt.dev/express-redis-app
        links:
          - redis
        ports:
          - 3000:3000
        environment:
          - REDIS_URL=redis://cache
          - NODE_ENV=development
          - PORT=3000
        command:
          sh -c 'node server.js'
    

Lastly, we need to tell Tilt how to build this image. Hereâs our Tiltfile:

    
    
    docker_compose('docker-compose.yml')
    docker_build('tilt.dev/express-redis-app', '.')
    

Now, when we run `tilt up`, Tilt will manage the image builds and re-build
every time a file changes.

## Using Tiltâs `live_update`

This works OK. But building a new image on every change can be a drag.

With the `live_update` option, we can make it a lot faster by updating the
container in-place.

Hereâs the new Tiltfile:

    
    
    docker_compose('docker-compose.yml')
    docker_build('tilt.dev/express-redis-app', '.',
      live_update = [
        sync('.', '/var/www/app'),
        run('npm i', trigger='package.json'),
        restart_container()
      ])
    

The `live_update` option is expressed as a sequence of in-place update steps.

  1. The `sync` step copies your local files into the running container.

  2. The `run` step re-runs `npm i` inside the container every time you edit `package.json`.

  3. The `restart_container` step restarts the server so that your changes are picked up.

For more info on `live_update`, check out the
[reference](live_update_reference.html).

## Multiple Compose Files

To use multiple [Docker Compose
files](https://docs.docker.com/compose/extends/), simply pass the list of
files to your `docker_compose` function.

    
    
    docker_compose(["./docker-compose.yml", "./docker-compose.override.yml"])
    

`docker_compose` also accepts a `blob` for any of its config items. You can
use this feature to provide overrides for your docker compose setup using
inline data from the `Tiltfile`, for example to take into account [config
flags](tiltfile_config.html):

    
    
    # Tell Tilt which services to enable debug by passing DEBUG=true to container environment
    # run as `tilt up -- --debug a`
    config.define_string_list('debug')
    cfg = config.parse()
    # flatten list; allow --debug a,b,c or --debug a --debug b --debug c
    debug_services = [item for sublist in [x.split(',') for x in cfg.get('debug', [])] for item in sublist]
    overrides = dict([(svc,{'environment':{'DEBUG': 'true'}}) for svc in debug_services])
    
    docker_compose(["./docker-compose.yml", encode_yaml({'services': overrides})])
    

## Debugging

Tilt uses Docker Compose to run your services, so you can also use `docker-
compose` to examine state outside Tilt.

## Organizing Services

The `dc_resource` Tiltfile function lets you pass options how your services
run:

[Labels](tiltfile_config.html#labels) let you control put services into
groups. The example repo contains these labels:

    
    
    dc_resource('redis', labels=["database"])
    dc_resource('app', labels=["server"])
    

If you have a server that doesnât need to run in every dev environment, you
can tell Tilt not to run it at startup:

    
    
    dc_resource('storybook', auto_init=False)
    

For a complete list of options, see [the API
reference](api.html#api.dc_resource).

## Try it Yourself

All the code in this tutorial is available in this repo:

[tilt-example-docker-compose](https://github.com/tilt-dev/tilt-example-docker-
compose)

Run it yourself and make changes to see how it works.

â Back to top  [ Edit on GitHub  ](https://github.com/tilt-
dev/tilt.build/tree/master/docs/docker_compose.md)







### Was this doc helpful?

Yes No