CentOS / RHEL 8 from sources¶
This guide describes how to install the GovReady-Q server for CentOS 8 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 as root:
# Update package list
dnf update
# Install dependencies
dnf install \
python3 python3-devel gcc-c++.x86_64 \
unzip git jq \
graphviz
# for pandoc, enable PowerTools repository (equivalent of CodeReady Linux Builder repo in RHEL 8)
dnf install dnf-plugins-core
dnf config-manager --set-enabled PowerTools
dnf install pandoc
# Upgrade pip to version 20.1+
pip install --upgrade pip
# Optionally install supervisord for monitoring and restarting GovReady-q; and NGINX as a reverse proxy
pip install supervisor
dnf install 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 dnf install xorg-x11-server-Xvfb https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox-0.12.6-1.centos8.x86_64.rpm ; fi
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 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
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 you 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"
# 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
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 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.
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 8 and CentOS 8 and tested on a CentOS 8.1.1911 Docker image.