Multi-Container GovReady-Q and NGINX via Docker Compose¶
Overview¶
This directory contains configuration files that run two Docker containers, one for GovReady-Q and the other for NGINX, as a multi-container app. NGINX is used in a reverse proxy configuration, to handle incoming HTTP and HTTPS requests, which it then passes to GovReady-Q.
Use Docker Compose to manage the multi-container app.
Docker Compose commands are similar to, but different from, regular Docker commands. Read the Docker Compose docs for more details.
Set Up A Docker Host¶
Workstation¶
Install Docker and Docker Compose on your workstation.
On Mac and Windows, Docker Compose is included as part of the Docker install.
On Linux, after installing Docker, install Docker Compose. Also, you may want to grant non-root users access to run Docker containers.
Docker Machine¶
Docker Machine can be used to set up Docker host on either a local or cloud server. Once you have configured your shell to connect to a Docker host set up by Docker Machine, the Docker Compose commands you need to use will be the same as if you were using the Docker engine running on your workstation as the Docker host.
Get This Kit¶
Get the files by cloning the GovReady-Q repository.
git clone https://github.com/GovReady/govready-q.git
cd govready-q/deployment/docker-compose-nginx/
Make sure you are in the ``docker-compose-nginx`` directory.
Any docker-compose
commands will need the docker-compose.yml
file to know which containers to operate on.
SSL/TLS Certificates for HTTPS¶
There are self-signed certs including in the nginx
directory. They
are copied into the nginx
container for nginx
to refer to.
Self-signed certs are sufficient to allow GovReady-Q and NGINX to work together with your browser. However, you will get a security exception notice from your browser, and you will have to approve the “unsafe” exception to proceed.
To use real certs issued against a CA your browser will recognize, you
can replace the cert.pem
and key.pem
files and issue the
docker-compose build
file, or you can mount a data volume with your
certs in it to /etc/pki/tls/certs/
.
Later versions of this project may include more documentation about the volume method, or other ways to include certs, such as Let’s Encrypt.
Build Images¶
You need to build images whenever you make changes to the Dockerfiles or
nginx
config file. If you don’t make changes, though, the command in
the next section will automatically build the images.
To build the images:
docker-compose build
Run GovReady-Q + NGINX Multi-container App¶
To start the containers:
docker-compose up -d
Using the -d
detaches the containers and runs them in the
background.
If you prefer, you can omit -d
, and then output will be printed to
your console window. If you hit ^C
, the containers will shut down
gracefully. If you hit ^C^C
they will be terminated immediately.
Two containers will be created, one for each “service” (as they’re called in Docker Compose).
Docker Compose gives these containers names like
docker-compose-nginx_govready-q_1
and
docker-compose-nginx_nginx_1
. These are three-part names, with the
parts separated by underscores. docker-compose-nginx
comes from the
name of this project (the directory it’s in). The second element is the
service name (govready-q
or nginx
). The third element is a
serial number (ascending from 1) for multiple instances of the same
service. The docker-compose.yml
file here only specifies one
instance, so the number will always be 1
.
You can check the status of the containers:
docker-compose ps
Specify Parameters¶
Before starting the containers, you can specify which GovReady-Q image to use, which database host to use, and the hostname of the Docker host. It’s important to specify the correct hostname if you are using real TLS certs.
Set these environment variables (sample values provided, replace with your own values):
export GOVREADY_Q_HOST=ec2-nnn-nnn-nnn-nnn.us-east-1.compute.amazonaws.com
export GOVREADY_Q_DBURL=postgres://govready_q:my_private_password@grq-002.cog63arfw9bib.us-east-1.rds.amazonaws.com/govready_q
export GOVREADY_Q_IMAGENAME=govready/govready-q-0.9.0
After setting the variables, continue with the “Run GovReady-Q + NGINX Multi-container App” section above.
If you don’t set environment variables, these defaults are used:
export GOVREADY_Q_HOST=test.example.com
export GOVREADY_Q_DBURL=
export GOVREADY_Q_IMAGENAME=govready/govready-q
When no DBURL is specified, GovReady-Q uses an internal sqlite database.
Check Logs From A Container¶
Check the logs by specifying the service name:
docker-compose logs govready-q
docker-compose logs nginx
GovReady-Q Is Up¶
GovReady-Q will boot up, and be ready to answer web requests in 20-30 seconds.
It will answer HTTP on the standard port, 80, and HTTPS on the standard port, 443.
Visit https://localhost/. (Or http://localhost
, which will be
redirected to https by nginx
.)
The default hostname used for this project is test.example.com
. To
check it, put this entry in your /etc/hosts
file:
127.0.0.1 test.example.com
When you have /etc/hosts
set up, visit https://test.example.com/
Execute A Script In A Container¶
You can exec a script inside one of the containers by specifying the
service name. Unlike normal docker
, you do not specify -it
to
make the exec interactive.
Here we are executing the first_run
script inside the govready-q
service/container.
docker-compose exec govready-q first_run