DEAR Petition

A Durham Expunction and Restoration (DEAR) project for creating petition forms.

• DEAR Petition
  • 🚀 Docker Quick Start (recommended)
  • Frontend Development
    • 🚀 Quick Setup
    • API Proxy Configuration
      • Docker Container
      • Local Frontend
  • Backend Development (with Docker)
    • Using docker-compose.override.yml
    • Initial Setup
    • Restore database
  • Backend Development (without Docker)
    • Setting Up a Virtual Environment
    • Setting Up Your Users
  • Development Tools and Testing
    • Type checks
    • Test coverage
    • Running tests with py.test
      • Docker
      • Without Docker
    • Sign up for Sentry
• Production testing

🚀 Docker Quick Start (recommended)

git clone git@github.com:deardurham/dear-petition.git
cd dear-petition
docker-compose up -d django
docker-compose run --rm django python manage.py migrate
docker-compose run --rm django python manage.py createsuperuser

Try out DEAR Petition Generator by logging in as the superuser you created and uploading test CIPRS records (in pdf format) which can be downloaded from https://github.com/deardurham/ciprs-reader/tree/main/tests/test_records

Frontend Development

The user facing side of the DEAR Petition Generator is a React single page app (SPA). It is common to run the frontend locally while running the backend on docker.

🚀 Quick Setup

npm i
npm run start

API Proxy Configuration

The Petition Generator app uses a React frontend with a Django REST API backend. In the development environment, the React development server and Django backend will likely be hosted on different ports, and thus hosted on different urls. This causes issues when the frontend code sends API requests, such as a login request. The solution is to proxy the API requests to the url of the backend.

Docker Container

When the frontend is run using docker, the API_PROXY environment variable is set to http://django:8000.

You can override the this proxy url by setting OVERRIDE_API_PROXY:

OVERRIDE_API_PROXY=http://localhost:8888 docker-compose up -d

Local Frontend

When using npm run start to run the frontend, the API_PROXY environment variable is unset. The fallback proxy is set to the http://localhost:8000.

You can set the proxy url by either setting OVERRIDE_API_PROXY or API_PROXY:

API_PROXY=http://localhost:8888 npm start

Backend Development (with Docker)

To run this on a Mac, use Docker for Mac.

Build the project containers:

docker-compose build

Run the containers:

docker-compose up django

Visit http://localhost:8000/petition/api/ in your browser. If you get authentication errors, you may login as the superuser you created at http://localhost:8000/ and try again.

Initial Setup

Migrate DB:

docker-compose run --rm django python manage.py migrate

Create a superuser:

docker-compose run --rm django python manage.py createsuperuser

When asked for a username and password, enter values of your choosing. Email address may be left empty.

See detailed cookiecutter-django Docker documentation.

Restore database

If you have a database dump you wish to restore, you can run:

docker-compose run --rm django sh
$ dropdb dear_petition
$ createdb dear_petition
$ pg_restore -Ox -d dear_petition latest.dump
$ python manage.py migrate

Configuring the containers using docker-compose.override.yml (optional)

To develop in a Docker container, we'll create a docker-compose.override.yml override file in the root of the dear-petition directory to configure the Django container to sleep by default:

# file: docker-compose.override.yml
version: '3'

services:
  django:
    command: ["sleep", "infinity"]

Now we run runserver manually to have more control over restarts:

docker-compose up -d django
docker-compose exec django bash
root$ python manage.py runserver 0.0.0.0:8000

Backend Development (without Docker)

Run the setup_project.py script from the base directory, providing as a command line argument the directory to the related ciprs-reader project. This will set up the project in your environment.

Setting Up a Virtual Environment

Developing inside a virtual environment is recommended.

On Mac run the following command to set up a virtual environment:

brew install pipenv
pipenv shell
pip install -r requirements/base.txt

On Linux run the following command to set up a virtual environment:

sudo yum install python-tools
pip3 install pipenv
pipenv shell
pip install -r requirements/base.txt

While inside of the pipenv run the setup_project.py script from the base directory, providing as a command line argument the directory to the related ciprs-reader project. This will set up the project in your environment.

python3 setup-project.py <path-to-ciprs-reader>

Additional Pipenv Notes: To exit the pip environment:

(dear-petition) bash-3.2$ exit
exit
bash-3.2$

To delete the pipenv environment:

bash-3.2$ pipenv --rm
Removing virtualenv (/Users/user/.local/share/virtualenvs/dear-petition-fJpn7FEC)…

Setting Up Your Users

• To create an superuser account, use this command:

  $ python manage.py createsuperuser
  

For convenience, you can keep your normal user logged in on Chrome and your superuser logged in on Firefox (or similar), so that you can see how the site behaves for both kinds of users.

Development Tools and Testing

Type checks

Running type checks with mypy:

$ mypy dear_petition

Test coverage

To run the tests, check your test coverage, and generate an HTML coverage report:

$ coverage run -m pytest
$ coverage html
$ open htmlcov/index.html

Running tests with py.test

Docker

$ docker-compose run --rm django pytest

Without Docker

$ pytest

Sign up for Sentry

The dear-petition project is now on Sentry. Visit sentry.io and make an account or sign in with Github. Reach out to an existing member for an invite to the project.

Production testing

To test the production Dockerfile locally, run:

COMPOSE_FILE=docker-compose.deploy.yml docker compose up --build -d django
# View logs for debugging
COMPOSE_FILE=docker-compose.deploy.yml docker compose logs django -f