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 Guide.

Setting Up Your Development Environment

Follow instructions listed at Developer Environment

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 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.

Invitations on local systems

You will probably want to try the invite feature at some point. The debug server is configured to dump all outbound emails to the console. So if you “invite” others to join you within the application, you’ll need to go to the console to get the invitation acceptance link.