This guide describes how to install the GovReady-Q server for CentOS 7 or greater from source code. This guide will take you through the following steps:
- Installing required OS packages
- Cloning the GovReady-Q repository
- Installing desired database
- Creating the local/environment.json file
- Installing GovReady-Q
- Starting and stopping GovReady-Q
- Running GovReady-Q with Gunicorn HTTP WSGI
- Monitoring GovReady-Q with Supervisor
- Using NGINX as a reverse proxy
- Additional options
GovReady-Q requires Python 3.6 or higher and several Linux packages to provide full functionality. Execute the following commands as root:
# Enable IUS repository
yum install \
https://repo.ius.io/ius-release-el7.rpm \
https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum update
# Install dependencies
yum install \
python36u python36u-pip \
unzip jq \
graphviz pandoc
# Upgrade pip to version 20.1+
pip3 install --upgrade pip
# Optionally install supervisord for monitoring and restarting GovReady-q; and NGINX as a reverse proxy
yum install supervisor nginx
# To generate thumbnails and PDFs for export, you must install wkhtmltopdf
# WARNING: wkhtmltopdf can expose you to security risks. For more information,
# search the web for "wkhtmltopdf Server-Side Request Forgery"
read -p "Are you sure (yes/no)? " ; if [ "$REPLY" = "yes" ]; then yum install xorg-x11-server-Xvfb wkhtmltopdf ; fi
GovReady-Q calls out to git
to fetch apps from git repositories, but that requires git version 2 or later because of the use of the GIT_SSH_COMMAND environment variable. The stock git on RHEL is version 1. Switch it to version 2+ by using the IUS package:
# If necessary, remove any git currently installed
yum remove git
# Install git222
yum install git222
You now need to decide where to install the GovReady-Q files and whether to run GovReady-Q as root or as a dedicated Linux user. Installing as root is convenient for initial testing and some circumstances. Creating a dedicated user and installing as that user is considered better practice.
Note
These steps assume you are installing into the /opt/
directory as root.
Clone the GovReady-Q repository from GitHub into the desired directory on your Ubuntu server.
cd /opt
# Clone GovReady-Q
git clone https://github.com/govready/govready-q /path/to/govready-q
cd govready-q
# GovReady-Q files are now installed in /opt/govready-q and owned by root
Note
These steps assume your are installing into the /home/govready-q
directory as user govready-q
.
While you are still root, create a dedicated Linux user govready-q
and home directory. Change directory into the created user's home directory and switch users to govready-q
. Clone the GovReady-Q repository from GitHub.
# Create user
useradd govready-q -m -c "govready-q"
chsh -s /bin/bash govready-q
cp /etc/skel/.bashrc /home/govready-q/.
chown govready-q:govready-q /home/govready-q/.bashrc
# Change permissions so that the webserver can read static files
chmod a+rx /home/govready-q
# Switch to the govready-q user
cd /home/govready-q
su govready-q
# Clone GovReady-Q
git clone https://github.com/govready/govready-q
cd govready-q
# GovReady-Q files are now installed in /home/govready-q/govready-q and owned by govready-q
GovReady-Q requires a relational database. You can choose:
- SQLite3
- MySQL
- PostgreSQL
GovReady-Q will automatically default to and use a SQLite3 database installed at local/db.sqlite3
if you do not specify a database connection string in local/environment.json
.
There is no setup necessary to use SQLite3. GovReady-Q will automatically install a local SQLite3 database local/db.sqlite3
by default if no db
parameter is set in local/environment.json
.
Note
All files in govready-q/local
are git ignored so that you can safely pull git updates.
On the database server, install MySQL OS packages:
# Install MySQL OS packages
sudo yum install -y mysql-devel
Make a note of the MySQL's host, port, database name, user and password to add to GovReady-Q's configuration file at local/environment.json
.
{
...
"db": "mysql://USER:PASSWORD@HOST:PORT/NAME",
...
}
On the database server, install PostgreSQL OS packages:
sudo apt install -y postgresql postgresql-contrib
# postgresql-setup initdb
Then set up the user and database (both named govready_q
):
sudo -iu postgres createuser -P govready_q
# Paste a long random password when prompted
sudo -iu postgres createdb govready_q
Postgres’s default permissions automatically grant users access to a database of the same name.
You must specify the database connection string in GovReady-Q's configuration file at local/environment.json
.
Make a note of the Postgres host, port, database name, user and password to add to GovReady-Q's configuration file at local/environment.json
.
{
...
"db": "postgres://USER:PASSWORD@HOST:PORT/NAME",
...
}
Encrypting your connection to PostgreSQL running on a separate database server
If PostgreSQL is running on a separate host, it is highly recommended you follow the instructions below to configure a secure connection between GovReady-Q and PostgreSQL.
In /var/lib/pgsql/data/postgresql.conf
, enable TLS connections by changing the ssl
option to
ssl = on
and enable remote connections by binding to all interfaces:
listen_addresses = '*'
Enable remote connections to the database only from the webapp server and only encrypted with TLS by editing /var/lib/pgsql/data/pg_hba.conf
and adding the line (replacing the hostname with the hostname of the Q webapp server):
hostssl all all webserver.example.com md5
Generate a self-signed certificate (replace db.govready-q.internal
with the database server’s hostname if possible):
openssl req -new -newkey rsa:2048 -days 365 -nodes -x509 -keyout /var/lib/pgsql/data/server.key -out /var/lib/pgsql/data/server.crt -subj '/CN=db.govready-q.internal'
chmod 600 /var/lib/pgsql/data/server.{key,crt}
chown postgres.postgres /var/lib/pgsql/data/server.{key,crt}
Copy the certificate to the webapp server so that the webapp server can make trusted connections to the database server:
cat /var/lib/pgsql/data/server.crt
# Place on webapp server at /home/govready-q/pgsql.crt
Restart the PostgreSQL:
service postgresql restart
And if necessary, open the PostgreSQL port:
firewall-cmd --zone=public --add-port=5432/tcp --permanent
firewall-cmd --reload
Create the local/environment.json
file with appropriate parameters. (Order of the key value pairs is not significant.)
SQLite (default)
{
"govready-url": "http://localhost:8000",
"debug": false,
"secret-key": "long_random_string_here"
}
MySQL
{
"db": "mysql://USER:PASSWORD@localhost:PORT/NAME",
"govready-url": "http://localhost:8000",
"debug": false,
"secret-key": "long_random_string_here"
}
PostgreSQL
{
"db": "postgres://govready_q:PASSWORD@localhost:5432/govready_q",
"govready-url": "http://localhost:8000",
"debug": false,
"secret-key": "long_random_string_here"
}
Note
As of 0.9.1.20, the "govready-url" environment parameter is preferred way to set Django internal security, url, ALLOWED_HOST, and other settings instead of deprecated environment parameters "host" and "https". The "host" and "https" deprecated parameters will continue to be supported for a reasonable period for legacy installs.
Deprecated (but supported for a reasonable period):
{
"db": "mysql://USER:PASSWORD@HOST:PORT/NAME",
"host": "localhost:8000",
"https": false,
"debug": false,
"secret-key": "long_random_string_here"
}
Preferred:
{
"db": "mysql://USER:PASSWORD@HOST:PORT/NAME",
"govready-url": "http://localhost:8000",
"debug": false,
"secret-key": "long_random_string_here"
}
See Environment Settings for a complete list of configuration options.
At this point, you have installed required OS packages; cloned the GovReady-Q repository; configured your preferred database option of SQLite3, MySQL, or PostgreSQL; and created the local/environment.json
file with appropriate settings.
Make sure you are in the base directory of the GovReady-Q repository. (Execute the following commands as the dedicated Linux user if you set one up.)
Run the install script to install required Python libraries, initialize GovReady-Q's database and create a superuser. This is the same command for all database backends.
# If you created a dedicated Linux user, be sure to switch to that user to install GovReady-Q
# su govready-q
# cd /home/govready-q/govready-q
# Run the install script to install Python libraries,
# initialize database, and create Superuser
./install-govready-q
Note
The command install-govready-q.sh
creates the Superuser interactively allowing you to specify username and password.
The command install-govready-q.sh --non-interactive
creates the Superuser automatically for installs where you do not have access to interactive access to the command line. The auto-generated username and password will be output (only once) to the stdout log.
Starting GovReady-Q
You can now start GovReady-Q Server. GovReady-Q defaults to listening on localhost:8000, but can easily be run to listen on other host domains and ports.
# Run the server on the default localhost and port 8000
python3 manage.py runserver
Visit your GovReady-Q site in your web browser at: http://localhost:8000/
# Run the server to listen at a different specific host and port
# python manage.py runserver host:port
python3 manage.py runserver 0.0.0.0:8000
python3 manage.py runserver 67.205.167.168:8000
python3 manage.py runserver example.com:8000
Stopping GovReady-Q
Press Ctrl-C
in the terminal window running GovReady-Q to stop the server.
In this step, you will configure your deployment to use a higher performing, multi-threaded gunicorn (Green Unicorn) HTTP WSGI server instead of GovReady-Q using Django's built-in server. This will serve you pages faster, with greater scalability. You will start gunicorn server using a config file which has settings to start GovReady-Q.
In this step, you will configure your deployment to use Supervisor to monitor and restart Gunicorn automatically if GovReady-Q should unexpectedly crash.
In this step, you will configure your deployment to use NGINX as a reverse proxy in front of Gunicorn as an extra layer of performance and security.
For situations in which more granular control over the install process is required, use the commands below for installing GovReady-Q.
# Clone GovReady-Q
git clone https://github.com/govready/govready-q
cd govready-q
# Install Python 3 packages
pip3 install --user -r requirements.txt
# Install Bootstrap and other vendor resources locally
./fetch-vendor-resources.sh
# Initialize the database by running database migrations (sqlite3 database used by default)
python3 manage.py migrate
# Load a few critical modules
python3 manage.py load_modules
# Create superuser with initial account interactively with prompts
python3 manage.py first_run
# Reply to prompts interactively
# Alternatively, create superuser with initial account non-interactively
# python3 manage.py first_run --non-interactive
# Find superuser name and password in output log
Note
The command python3 manage.py first_run
creates the Superuser interactively allowing you to specify username and password.
The command python3 manage.py first_run --non-interactive
creates the Superuser automatically for installs where you do not have access to interactive access to the command line. The auto-generated username and password will be output (only once) to to the stdout log.
To activate PDF and thumbnail generation, add gr-pdf-generator
and gr-img-generator
environment variables to your local/environment.json
configuration file:
{
...
"gr-pdf-generator": "wkhtmltopdf",
"gr-img-generator": "wkhtmltopdf",
...
}
GovReady-Q can be optionally deployed with NGINX and Supervisor. There's also a script for updating GovReady-Q.
Sample nginx.conf
, supervisor.conf
, and update.sh
files can be found in the source code directory deployment/ubuntu
.
Instructions applicable for RHEL 7 and CentOS 7 tested on a CentOS 7.8.2003 Docker image.