CentOS / RHEL 7 from sources¶
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
1. Installing required OS packages¶
GovReady-Q requires Python 3.6 or higher and several Linux packages to provide full functionality. Execute the following commands:
# Enable IUS repository
sudo yum install https://centos7.iuscommunity.org/ius-release.rpm
sudo yum update
# Install dependencies
sudo yum install \
python36u python36u-pip \
unzip git2u jq \
graphviz pandoc
# Upgrade pip to version 20.1+
python3 -m pip install --upgrade pip
# Optionally install supervisord for monitoring and restarting GovReady-q; and NGINX as a reverse proxy
DEBIAN_FRONTEND=noninteractive \
apt-get install -y 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 sudo 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
sudo yum remove git
# Install git2u
sudo yum install git2u
Upgrading pip on RHEL 7¶
Upgrade pip
because the RHEL package version is out of date (we need
>=9.1 to properly process hashes in requirements.txt
)
pip3 install --upgrade pip
2. Cloning the GovReady-Q repository¶
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.
2 (option a). Installing as root¶
Note
These steps assume your 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
2 (option b). Installing as Linux user “govready-q”¶
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 govready-q
3. Installing desired database¶
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
.
3 (option a). Installing SQLite3 (default)¶
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.
3 (option b). Installing MySQL¶
On the database server, install MySQL OS packages:
# Install of 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",
...
}
3 (option c). Installing PostgreSQL¶
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
4. Creating the local/environment.json file¶
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 support for 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.
5. Installing GovReady-Q¶
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.
6. Starting and stopping GovReady-Q¶
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.
7. Running GovReady-Q with Gunicorn HTTP WSGI¶
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.
8. Monitoring GovReady-Q with Supervisor¶
In this step, you will configure your deployment to use Supervisor to monitor and restart Gunicorn automatically if GovReady-Q should unexpectedly crash.
9. Using NGINX as a reverse proxy¶
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.
10. Additional options¶
Installing GovReady-Q Server command-by-command¶
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.
Enabling PDF export¶
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",
...
}
Deployment utilities¶
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
.
Notes¶
Instructions applicable for RHEL 7 and CentOS 7 and tested on a CentOS 7.8.2003 Docker image.