manage.get.gov/docs/developer

Development

========================

If you're new to Django, see Getting Started with Django for an introduction to the framework.

Local Setup

• Install Docker https://docs.docker.com/get-docker/

• Initialize the application:

  cd src
  docker-compose build
  

• Run the server: docker-compose up

  Press Ctrl-c when you'd like to exit or pass -d to run in detached mode.

Visit the running application at http://localhost:8080.

Setting Vars

Non-secret environment variables for local development are set in src/docker-compose.yml.

Secrets (for example, if you'd like to have a working Login.gov authentication) go in .env in src/ with contents like this:

DJANGO_SECRET_LOGIN_KEY="<...>"

You'll need to create the .env file yourself. Get the secrets from Cloud.gov by running cf env getgov-unstable.

Viewing Logs

If you run via docker-compose up, you'll see the logs in your terminal.

If you run via docker-compose up -d, you can get logs with docker-compose logs -f.

You can change the logging verbosity, if needed. Do a web search for "django log level".

Running tests

Crash course on Docker's run vs exec: in order to run the tests inside of a container, a container must be running. If you already have a container running, you can use exec. If you do not, you can use run, which will attempt to start one.

To get a container running:

cd src
docker-compose build
docker-compose up -d

Django's test suite:

docker-compose exec app ./manage.py test

OR

docker-compose exec app python -Wa ./manage.py test  # view deprecation warnings

Linters:

docker-compose exec app ./manage.py lint

Accessibility Scanning

The tool pa11y-ci is used to scan pages for compliance with a set of accessibility rules. The scan runs as part of our CI setup (see .github/workflows/test.yaml) but it can also be run locally. To run locally, type

docker-compose run pa11y npm run pa11y-ci

The URLs that pa11y-ci will scan are configured in src/.pa11yci. When new views and pages are added, their URLs should also be added to that file.

USWDS and styling

We use the U.S. Web Design System (USWDS) for building and styling our applications. Additionally, we utilize the uswds-compile tool from USWDS to compile and package the static assets. When you run docker-compose up the node service in the container will begin to watch for changes in the registrar/assets folder, and will recompile once any changes are made. Within the registrar/assets folder, the _theme folder contains three files initially generated by uswds-compile:

1. _uswds-theme-custom-styles contains all the custom styles created for this application
2. _uswds-theme contains all the custom theme settings (e.g. primary colors, fonts, banner color, etc..)
3. styles.css a entry point or index for the styles, forwards all of the other style files used in the project (i.e. the USWDS source code, the settings, and all custom stylesheets).

You can also compile the sass at any time using npx gulp compile. Similarly, you can copy over other static assets (images and javascript files), using npx gulp copyAssets.