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

git clone [email protected]: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

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.

npm i
npm run start

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.

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

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

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.

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.

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

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

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.

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)…

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

Running type checks with mypy:

$ mypy dear_petition

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

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

$ docker-compose run --rm django pytest

$ pytest

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.

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