macOS from sources

This guide describes how to install the GovReady-Q server for macOS 10.10 or greater from source code.

Note

These instructions have not been recently tested.

Installing required OS packages

GovReady-Q requires Python 3.6 or higher to run and several Unix packages to provide full functionality. Install the Homebrew package manager (https://brew.sh) to easily install Unix packages on macOS. Homebrew will install all packages in your userspace and not change native macOS Python or other libraries. Execute the following commands:

# install Homebrew package manager
       /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Now install Python3 and the required Unix packages.

 # install dependencies using brew
 brew install python3

 # install other packages:
 brew install unzip graphviz pandoc selenium-server-standalone magic libmagic

 # 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 brew cask install wkhtmltopdf ; fi

# Upgrade pip to version 20.1+ - IMPORTANT
python3 -m pip install --upgrade pip

# Optionally install supervisord for monitoring and restarting GovReady-q; and NGINX as a reverse proxy
apt-get install -y supervisor nginx

# To optionally 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 you need to generate PDF files (yes/no)? " ; if [ "$REPLY" = "yes" ]; then apt-get install wkhtmltopdf ; fi

Warning

The default version 9.0.x of pip installed on Ubuntu (May 2020) correctly installs Python packages when run as root, but fails when run as non-root user and does not report the error clearly. (Pip 9.0.x fails to create the user’s .local directory for installing the packages.) Upgrading pip to version 20.x solves this problem. Pip must be upgraded to 20.x for the ./install-govready-q script to properly install the Python packages.

Installing GovReady-Q

Clone the GovReady source code and install packages.

# 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
# (sudo needed only for the embedded 'yum install' command)
sudo ./fetch-vendor-resources.sh

Setting up GovReady-Q

Run the final setup commands to initialize a local SQLite database in local/db.sqlite to make sure everything is OK so far.

The following warning message is expected and okay:

WARNING: Specified PDF generator is not supported. Setting generator to ‘off’.

# run 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
python3 manage.py first_run

Starting GovReady-Q

# run the server
python3 manage.py runserver 0.0.0.0:8000

Visit your GovReady-Q site in your web browser at:

http://localhost:8000/

It is not necessary to specify a port. GovReady-Q will read the local/environment.json file to determine host name and port.

# run the server
python3 manage.py runserver

Note

Depending on host configuration both python3 and python commands will work.

GovReady-Q can run on ports other than 8000. Port 8000 is selected for convenience.

GovReady-Q defaults to localhost:8000 when launched with python manage.py runserver.

Tested on a CentOS 7.8.2003 Docker image on 2020-05-04.

(Optional) Installing Postgres, MySQL

GovReady-Q can optionally be configured to work with Postgres or MySQL database engines instead of the default SQLite3.

# optional install of postgres and/or mysql
sudo yum install postgresql mysql-devel
# if you intend to use optional configurations, such as the MySQL adapter, you
# may need to run additional `pip3 install` commands, such as:
pip3 install --user -r requirements_mysql.txt

Creating “environment.json” configuration file

GovReady uses a configuration file stored at local/environment.json.

See ref:Configuration with Environment Variables for a complete list of variables you can configure.

Create a file there and include values like these:

{
  "debug": false,
  "host": "localhost:8000",
  "https": false,
  "secret-key": "...something here..."
}

(Optional) 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",
   ...
}

(Optional) Deployment utilities

Sample apache.conf, superviser.ini, and update.sh files can be found in the source code directory deployment/rhel.

(Optional) Creating a dedicated GovReady UNIX user

You may find it useful to create a user specifically for GovReady-Q. Do this before installing GovReady-Q.

# Create user.
useradd govready-q -c "govready-q"

# Change permissions so that the webserver can read static files.
chmod a+rx /home/govready-q