Developer Environment¶

In order to support GovReady-Q’s Open Source community we have provided an easy and quick way to setup a developer’s environment. Developer environment code lives in the dev_env directory.

1. Install:¶

Docker (https://docs.docker.com/engine/installation/)
Docker Compose (https://docs.docker.com/compose/install/)
Python (3+) (https://www.python.org/downloads/)

Note

If desired, grant non-root users access to run Docker containers (https://docs.docker.com/engine/installation/linux/linux-postinstall/#manage-docker-as-a-non-root-user). Otherwise use sudo or a root user. User needs to be able to open ports as well.

2. Configuration¶

All development environment files are managed in two directories:

dev_env - This directory holds all files to setup and maintain the developer’s environment

local - This directory holds all artifacts that persist between runs

To modify Govready-Q settings, you’ll need to generate an environment.json to pass to the container. This is modifiable at any time.

# Change to dev_env directory
cd dev_env

#  This will generate dev_env/docker/environment.json
python run.py init

Warning

A restart will be required if you modify the values between runs.

Keys and Description - environment.json¶

Title¶
Key	Data Type	Default	Description
`admins`	Object[]	[]	Used to configure a display point of contact “Administrator” on site and unrelated to the configuration of actual administrators configured in the database Ex: `[{"username": "username", "email":"first.last@example.com", "password": "REPLACEME"}]`.
`branding`	string	“”	Directory name used for custom branding.
`db`	string	“postgres://postgres:PASSWORD@postgres_dev:5432/govready_q”	If supplied, this is the DB connection used. See Database Support.
`debug`	boolean	true	Turns on certain debug/development settings.
`email`	Object	{}	used to configure access to a mail server for sending and receiving email. Object has the following format: `{"host": "smtp.server.com", "port": "587", "user": "...", "pw": "....", "domain": "webserver.example.com"}`.
`enable_toolbar`	boolean	false	Enables Django Debug Toolbar in for troubleshooting
`govready_cms_api_auth`	string	“”	Used to store API key to interact with GovReady’s CMS agent and dashboard. Not relevant to most users.
`govready-url`	string	“http://localhost:8000”	this is the fully qualified URL that would appear in public URLS to navigate to the GovReady instance. This is the preferred parameter
`mailgun_api_key`	string	“”	Used to hold API key for using mailgun to send/receive emails.
`memcached`	boolean	false	If setting is true, enable a memcached cache using the default host/port
`secret-key`	string	`This is autogenerated for you`	Used to make instance more secure by contributing a salt value to generating various random strings and hashes. Do not share.
`gr-pdf-generator`	string	“wkhtmltopdf”	Specifies the library/process used to generate PDFs, options are off and wkhtmltopdf and default is None in production.
`gr-img-generator`	string	“wkhtmltopdf”	Specifies the library/process used to generate images and thumbnails, options are off and wkhtmltopdf and default is None in production.
`syslog`	string	“”	Used to set the host and port of a syslog-compatible log message sink. (Default: None.)
`trust-user-authentication-headers`	Object	{}	Used to activate reverse proxy authentication. See Proxy Authentication Server.
`oidc`	Object	{}	Used to enable OIDC SSO. See OpenID Connect.
`okta`	Object	{}	Used to enable Okta SSO. See Okta OpenID Connect.

3. Running GovReady-Q¶

For the purposes of rapid development GovReady-Q uses the default SQLite database.

# Change to dev_env directory
cd dev_env

# This will run + reuse previously built artifacts (database, files, etc)
python run.py dev

# This will run + destroys your existing database and artifacts from previous runs
python run.py dev --clean

# Stops the server but keeps persisted items (database volume, artifacts, etc)
python run.py remove

# Destroys your existing database and artifacts from previous runs
python run.py wipedb

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

http://localhost:8000/

Warning

The GovReady-Q default Postgres Database will be created within the docker-compose stack. This will persist between runs. Use the –clean flag or wipedb command to remove persisted items.

4. IDE Interpreter Setup¶

In order to develop on your host system, we have built in a SSH server to the govready_q container. This allows the host to connect to a remote interpreter and still leverage intelisense even though the container has the code and dependencies installed.

Note

This installation type mounts the entire repo to the govready_q container. This means that it supports bi-directional file changes. In other words, any changes to the files on the Host system will update in the container and conversely all changes in the container will be reflected on the Host system. This is meant to allow the developer to program where they feel most comfortable.

Pycharm¶

File -> Settings -> Project -> Project Interpreter  -> Cog -> Add -> SSH Interpreter

- Host: localhost
- Port: 2222
- User: root
- Password: root
- Interpreter: /usr/src/app/dev_env/docker/remote_interpreter/python_env.sh

VI / VIM¶

# Connect to the Django container directly to code.
docker exec -it govready_q /bin/bash

5. Debugging GovReady-Q¶

In order to do interactive debugging we have included ipdb (https://github.com/gotcha/ipdb), but you can use other methods if preferred.

Using Breakpoints¶

For example, I put a breakpoint (ipdb.set_trace()) to check the login process. docker-compose will display the breakpoint output, however you cannot interact with it that way. You must attach to the container to interact with the tty.

Example:

def homepage(request):
    import ipdb; ipdb.set_trace()
    if request.user.is_authenticated:
        return HttpResponseRedirect("/projects")
    from allauth.account.forms import SignupForm, LoginForm

# Attaches to the container and allows you to interact with the breakpoint; Also good for viewing logs
docker attach govready_q

Note

After attaching, you will remain attached the rest of the docker-compose session. You’ll be able to resuse this terminal for all breakpoints during this session.

Warning

Using ctrl+c will send a SIGKILL to the container and force a restart. To detach without a restart use ctrl+pq

Running commands against Container¶

You never know what you’ll have to do during development. Since the govready_q container uses Docker, you can send any commands you wish via the exec functionality. It can be Django commands, Ubuntu specific tasks, or simply connecting to a Bash terminal within the container.

Examples:

# Bash
docker exec -it govready_q /bin/bash

# Django Command
docker exec -it govready_q python3 manage.py shell

# top
docker exec -it govready_q top

6. FAQ¶

What runs every time in python run.py dev?

migrations : We need to apply migrations between branches
pip installs: We cannot assume libraries will remain static between branches

Docker is eating too much RAM. What can I do?

Windows - https://medium.com/@lewwybogus/how-to-stop-wsl2-from-hogging-all-your-ram-with-docker-d7846b9c5b37

How are my changes propagated to and from the container?

In the “dev_env/docker/docker-compose.yaml” we have a volume set to “../..:/usr/src/app” under govready-q. This sets up a bi-driectional mount.
Any changes to the host will affect the container and any changes to the container will affect the host.

When do I rebuild the container?

This happens automatically. If a change is detected in the Dockerfile, the next time you restart it will rebuild the container.

How do I see logs or interact with a debugger?

See 5. Debugging GovReady-Q.

How do I run management commands or interact with the container?

See Running commands against Container.

I just switched branches and my database is out of sync. What do I do?

Exit the existing run by hitting “ctrl-c”; then:

# This will clean up all artifacts and will wipe the existing database for a fresh run
python run.py dev --clean