Running in Docker¶
First, follow the Docker installation instructions to setup your Docker environment and create the project Docker containers.
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.
The following URLs are mapped to your host from the containers:
- Access cfgov-refresh running in the Python 2.7 container: http://localhost:8000/
- Access cfgov-refresh running in the Python 3.6 container: http://localhost:8333/
- Access Elasticsearch: http://localhost:9200/
- View this documentation: http://localhost:8888/
To build and run the containers for the first time, run:
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
stop docker-compose with Ctrl+C,
and start it again with
Access a container's shell¶
- Python 2.7:
docker-compose exec python2 bash
- Python 3.6:
docker-compose exec python3 bash
docker-compose exec elasticsearch bash
docker-compose exec postgres bash
Run Django management commands¶
manage.py commands can only be run after you've
opened up a shell in one of the Python containers.
From there commands like
cfgov/manage.py migrate should run as expected.
The same goes for scripts like
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
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:
docker-compose up --build python2 python3
Work on satellite apps¶
Attach for debugging¶
- 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
Useful Docker commands¶
[SERVICE] is the service name that is defined in
[CONTAINER] is the container name displayed with
docker pswill list all containers.
docker logs [CONTAINER]will print the logs of a container.
docker top [CONTAINER]will display the running processes in a container.
docker-compose build [SERVICE]will build any of our configured containers.
Production-like Docker Image¶
This repository includes a "production-like" Docker image, created for experimenting with how cf.gov could be built and run as a Docker container in production.
- all relevant
- all OS, Python, and JS dependencies for building and running the cf.gov webapp
- procedures for executing Django
yarn-based frontend build process
- an Apache HTTPD webserver with
mod_wsgi, run with configs in
How do I use it?¶
If you just want to build the image:
docker build . --build-arg scl_python_version=rh-python36 -t your-desired-image-name
scl_python_version build arg specifies which
Python Software Collection
version you'd like to use. We've tested this against
You can also launch the full cf.gov stack locally via
docker-compose. This setup is
a nice way to test out new Apache config changes. It includes volumes that mount your
cfgov/apache config directories into the container, allowing you to
change configs locally without having to rebuild the image each time.
Launch the stack.
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up --build
This create containers running Python 2.7 and 3.6 versions of cf.gov, as well as Postgres and Elasticsearch containers, much like the development environment.
cfgovdatabase (optional). If you do not already have a running
cfgovdatabase, you will need to download and load it from within the container.
docker-compose exec python2 bash # Once in the container... export CFGOV_PROD_DB_LOCATION=<database-dump-url> ./refresh-data.sh
Browse to your new local cf.gov site.
Adjust an Apache
cfgov/apacheconfig and reload Apache (optional).
docker-compose exec python2 bash # Once in the container... httpd -d ./cfgov/apache -k restart
Switch back to the development Compose setup.
docker-compose rm -sf python3 python2 docker-compose up --build python3 python2
How does it work?¶
The production image extends the development image. If you look at the
Dockerfile, this is spelled out by the line:
FROM cfgov-dev as cfgov-prod
Both 'cfgov-dev' and 'cfgov-prod' are called "build stages". That line means, "create a new stage, starting from cfgov-dev, called cfgov-prod".
From there, we:
- Install SCL-based Apache HTTPD, and the
mod_wsgiversion appropriate for our chosen
- Run frontend.sh, Django's collectstatic command, and then uninstall node and yarn.
- Set the default command on container startup to
httpd -d ./cfgov/apache -D FOREGROUND, which runs Apache using the configuration in cfgov-refresh, in the foreground (typical when running Apache in a container).