Running in Docker

First, follow the Docker installation instructions to setup your Docker environment and create the project Docker containers.

We use docker-compose to run an Elasticsearch container, a PostgreSQL container, and Django in Python 2.7 and 3.6 containers. There is also a container serving the documentation.

All of these containers are configured in our docker-compose.yml file. See the Docker documentation for more about the format and use of this file.

The following URLs are mapped to your host from the containers:

To build and run the containers for the first time, run:

docker-compose up

Environment variables

Environment variables from your .env file are sourced when the Python containers start and when you access the running Python containers. Your local shell environment variables, however, are not visible to applications running in Docker. To add new environment variables, simply add them to the .env file, stop docker-compose with Ctrl+C, and start it again with docker-compose up.

Access a container's shell

  • Python 2.7: docker exec -it cfgov-refresh_python2_1 bash
  • Python 3.6: docker exec -it cfgov-refresh_python3_1 bash
  • Elasticsearch: docker exec -it cfgov-refresh_elasticsearch_1 bash
  • PostgreSQL: docker exec -it cfgov-refresh_postgres_1 bash

Run Django management commands

Django commands can only be run after you've opened up a shell in one of the Python containers. From there commands like cfgov/ migrate should run as expected.

The same goes for scripts like ./ and ./ — they will work as expected once you're inside the container.


Because both Python containers use the same database (in the PostgreSQL container), any management commands or scripts that operate on the database (like migrate,, and should only be run once in one of the two Python containers.

Update Python dependencies

If the Python package requirements files have changed, you will need to stop docker-compose (if it is running) and rebuild the Python containers using:

  • Python 2.7: docker-compose build python2
  • Python 3.6: docker-compose build python3

The next time you run docker-compose up the new requirements will be in place.

Work on satellite apps

See Related Projects#Using Docker.

Attach for debugging

If you have inserted a PDB breakpoint in your code and need to interact with the running Django process when the breakpoint is reached you can run docker attach:

  • Python 2.7: docker attach cfgov-refresh_python2_1
  • Python 3.6: docker attach cfgov-refresh_python3_1

When you're done, you can detach with Ctrl+P Ctrl+Q.

Useful Docker commands

For docker-compose commands, [CONTAINER] is the container name that is defined in docker-compose.yml.

For docker commands, [CONTAINER] is the container name displayed with docker ps.