Developing for Govready-Q¶

These pages cover topics related to working with the source of GovReady-Q.

You may also want to refer to the Installation and Setup section of the guide, and either Desktop Installation or Server-based Installation, depending on your development environment.

Contents

Examples for Setting Up Your Development Environment¶

.bashrc¶

The .bashrc file is THE file that will make your life a lot easier once you have a couple settings set.

To view your .bashrc file enter the following commands.

cd ~
cat .bashrc

We will be entering three lines at the end of this file.

1. Change directory directly to your govready-q root¶

cd "/mnt/../path/to/govready-q"

2. The virtual environment activation command¶

source <virtualenv>/bin/activate

Common values for <virtualenv> are venv or env. GovReady-Q’s .gitignore is set up for env.

3. The alias to open any directory in the given filesystem with PyCharm `charm . &`¶

alias charm="/mnt/path/to/JetBrains/'<version number>'/bin/pycharm64.exe"

For example, <version number> could be PyCharm 2020.1.1.

Locate the absolute path to pycharm64.exe with which pycharm64.exe. Single quotes must be placed around parts of the path that aren’t contiguous. For example the version number should be entered as ‘PyCharm 2020.1.1’.

PyCharm¶

PyCharm Professional is one of the IDEs we prefer, and it has many tools and features that you will find enhance development experience and we will explore a few here.

This first tip is primarily for Windows users using WSL to develop.

The terminal shell used can be configured¶

File | Settings | Tools | Terminal for Windows and Linux

PyCharm | Preferences | Tools | Terminal for macOS Ctrl+Alt+S

Tools > terminal location¶

Default command-line terminal¶

Linux command-line terminal¶

WSL Terminal panel¶

Management Commands¶

GovReadyQ’s manage.py uses django.core.management to orchestrate management commands.

Implementation¶

from django.core.management import execute_from_command_line

execute_from_command_line(sys.argv)

I will summarize the fantastic documentation the Django development team has for BaseCommand in order for you to create your own commands. Bottom line, we create a new class that inherits from the Django object BaseCommand.

For this walk-through I will outline how the management command ./manage.py compliance_app allows us to list all available app sources.

First and foremost we need to ensure we have a management/commands directory under the Django app of choice, in this example guidedmodules (which registers the command when guidedmodules is included in INSTALLED_APPS). Then a new file compliance_app.py for our compliance_app command argument. In this file we import and inherit BaseCommand into our new class. Adding some help text to remind us of this commands purpose.

Note

We are now in ~/govready-q/guidedmodules/management/commands/compliance_app.py

from django.core.management.base import BaseCommand

class Command(BaseCommand):
    help = 'Creates a new compliance app. Lists available appsource names if no command-line arguments are given.'

We can now add override the handle method which is the only required implementation. An overview provided here.

class Command(BaseCommand):

...

def handle(self, *args, **options):
     # if no appsource specified
         # Show valid appsources by iterating through all AppSource objects and prints the slug name and path

     # other argument logic that includes appsource specified

For additional arguments compliance_app also overrides add_arguments. Here we specify the argument to enter ('appsource'), the number of arguments ("?"), and its type (str). These arguments are then implemented in the handle override.

class Command(BaseCommand):

...

def add_arguments(self, parser):
     parser.add_argument('appsource', nargs="?", type=str)
     parser.add_argument('--path', nargs="?", type=str)
     parser.add_argument('appname', nargs="?", type=str)

...

Currently Implemented¶

guidedmodules

Command

Usage Notes

./manage.py apps_catalog

Lists all apps in the configured app stores

./manage.py assemble --init path/to/app assemble.yaml

creating an ‘empty’ YAML file for a given app

./manage.py assemble assemble.yaml outdir

Make a directory mkdir outdir. Then assemble the app’s output documents to an output

./manage.py assemble --startapps assemble.yaml

Start component apps automatically

./manage.py compliance_app

lists available app sources

./manage.py compliance_app mysource

creates a new local AppSource named mysource

./manage.py compliance_app mysource myapp

creates a new app at path/to/apps/myapp

./manage.py load_modules

Updates the system modules from the YAML specifications in AppSources

./manage.py upgrade_project

Upgrades a project to a new version of an app or associates it with a different compliance app

siteapp

Command

Usage Notes

./manage.py db_before_090

Check if version 0.9.0 migration has been run. Return “False” if database not initialized or 0.9.0 migrations has been run

./manage.py first_run

Interactively set up an initial user and organization

./manage.py first_run --non-interactive

Non-interactively set up an initial user and organization

./manage.py send_notification_emails

Sends emails for notifications

./manage.py send_notification_emails forever

Sends emails for notifications forever

./manage.py test_screenshots

Generate screenshots of the application using Selenium for creating test artifacts and documentation. Run on non-production servers only.

siteap.test_screenshots arguments

Note

Need chromedriver.exe available in PATH for Selenium

A throwaway test database is used so that this command cannot see any existing user data, and database changes are not persistent. However, it would not be advisable to run this command on a production system.

Examples:

Create screenshots for the FISMA Level app:
./manage.py test_screenshots --app-source '{ "slug": "govready-apps-dev", "type": "git", "url": "https://github.com/GovReady/govready-apps-dev", "path": "apps" }' \
--app govready-apps-dev/fisma_level \
--path screenshots.pdf
The --app-source argument can be repeated multiple times if more than one AppSource is needed to run the script.

Create screenshots for authoring a new app and set (approximate) output image size:
./manage.py test_screenshots --author-new-app \
                         --path screenshots.pdf \
                         --size 1024x768
Argument

Usage Notes

./manage.py test_screenshots --org-name

The name of the temporary Organization that will be created.

./manage.py test_screenshots --app-source {source JSON}

An AppSource definition in JSON. This argument can be repeated.

./manage.py test_screenshots --app [source/app]

The AppSource slug plus app name of a compliance app to fill out.

./manage.py test_screenshots --test [testid]

The ID of the test to run defined in the app’s app.yaml ‘tests’ key, or @filename to load a test from a YAML file.

./manage.py test_screenshots --author-new-app

Take screenshots for Q documentation showing how to author a new compliance app.

./manage.py test_screenshots --path [dir_or_pdf]

The path to write screenshots into, either a directory or a filename ending with .pdf.

./manage.py test_screenshots --size [widthXheight]

The width and height, in pixels, of the headless web browser window, or ‘maximized’.

./manage.py test_screenshots --mouse-speed [seconds]

Each mouse move will have this duration.

./manage.py test_screenshots --version

Show program’s version number and exit

./manage.py test_screenshots -v {0,1,2,3}, --verbosity {0,1,2,3}

Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output

./manage.py test_screenshots --settings SETTINGS

The Python path to a settings module, e.g. “myproject.settings.main”. If this isn’t provided, the DJANGO_SETTINGS_MODULE environment variable will be used.

./manage.py test_screenshots --pythonpath PYTHONPATH

A directory to add to the Python path, e.g. “/home/djangoprojects/myproject”.

./manage.py test_screenshots --traceback

Raise on CommandError exceptions

./manage.py test_screenshots --no-color

Don’t colorize the command output.

./manage.py test_screenshots --force-color

Force colorization of the command output.

./manage.py test_screenshots --skip-checks

Skip system checks.