Local Development

Compose has commands for managing the whole lifecycle of your application:

  • Start, stop services
  • View the status of running services
  • Stream the log output of running services
  • Run a one-off command on a service

Local Development

To bring up dev environment initially:

$ docker-compose -f docker-compose.dev.yml up -d

Or, to rebuild and then bring up the containers:

$ docker-compose -f docker-compose.dev.yml up --build -d

Note: The -f flag denotes a custom compose file, while the -d flags brings it up in detached mode. This allows you to run other commands in the same shell (you may want to run it without the -d flag to see docker’s log, and open another terminal tab to run commands).

Dev environment will run the server using runserver_plus (although you can always disable that in docker-compose and use the native runserver). It will use the same PostgreSQL database that production uses. Also, start-dev.sh runs migrations prior to starting the server. Modify that shell script as you wish to specify the dev tools you’d like to use.

NOTE: Using the --build flag creates a new image each time. Run inv rm_images to clean up; that command is also run by a cron job once a day. Regardless, try to minimize the use of the build command; most code changes are reloaded through the server. Changes in requirements, some setting definitions, and migrations should use the build flag.

You can bring the development environment down using invoke:

$ invoke dev_stop


To use breakpoints, insert one like normal using ipdb:

import ipdb; ipdb.set_trace()

When bringing up the containers, use the --service-ports flag to ensure the correct links are setup; the ipdb shell should start when the breakpoint is hit (For example, if you’re running tests”)


If you start a service configured with links, the run command first checks to see if the linked service is running and starts the service if it is stopped. Once all the linked services are running, the run executes the command you passed it. So, for example, you could run:

$ docker-compose run db psql -h db -U postgres

Which opens an interactive PostgreSQL shell for the linked db container. Following the same style, the following would start a Django shell session. Due to limitations regarding where you can start a shell, make use of shell_plus when appropriate/

$ docker-compose run web python manage.py shell

Open a bash shell:

$ docker-compose run web /bin/bash

Use the --service-ports flag to map the services ports to the host.

Running Tests

Running tests is simple. When bring the containers up, you can specify more than one docker-compose file with the -f flag. So, the following command would bring up the dev environment, but the test file runs instead of docker-compose.dev.yml’s runserver:

$ docker-compose -f docker-compose.dev.yml -f docker-compose.test.yml up


Find a better way to interactiveley run tests!