RecordSponge

A project to automate expunging qualifying criminal records. This project is done in conjunction with Qiu-Qiu Law. Learn more in the wiki.

If you're interested in learning more about our project and getting involved, please join us at one of our meetup events!

Table of Contents

• Tech Overview
• Installation
• Running Components
• Testing
• Contributing
• Technical Documentation
• License

Tech Overview

This is a web app built using React for the in-browser interface, and a backend web service implemented with the Flask web framework in Python.

Our dev environment is entirely containerized with Docker, and no other dependencies need to be installed natively. We use Python's pipenv for maintaining backend dependencies. We use mypy to type check any optional typings and pytest to test backend code. We use NPM to develop and build the frontend code. Docker is used to build and deploy the app stack for both local development and for deployment to the web.

Installation

You can get your dev environment up and running with installing only Docker and docker-compose. The npm and backend dev servers run in docker containers, synced with source code directories so that code changes propagate on the local servers right away.

1. Fork the repo to create a copy for your own github account, and clone your own copy. (Read CONTRIBUTING.md for important info about syncing code your on github)

2. Install docker

   • Mac

     • Follow installation instructions in: Getting Started -- Docker on Mac OS X

       (click on Get Docker for Mac [Stable])

   • Linux

     • First, follow: Docker Installation

     • Configure your user to run docker without sudo: https://docs.docker.com/install/linux/linux-postinstall/

     • Install docker-compose

   • Windows

     • Windows (as always) is a bit more challenging. Docker CE on Windows requires Hyper-V support, which is only available on Windows 10 Pro, Enterprise, or Education. If you have one of those versions, follow Docker's documentation to install Docker Engine.
     • If you have Hyper-V:
       • Install GNU Make for Windows using either Chocolatey or by downloading the executable from sourceforge, running the installer, and then putting the binary on your Path Environment variable.
     • If you have Windows 10 Community, Home, or other versions, create a Linux VM using VirtualBox and run Docker Engine through there. Alternately, you could partition your hard drive and dual-boot Linux to use for development.

     • Important Windows Note

       if your git config changes Linux-style line endings into windows-style line endings using the core.autocrlf config flag, you'll need to disable that in order for the docker builds to work correctly. You can disable this setting for just the recordexpungPDX repo by running git config --local core.autocrlf false from the root directory of this repo.

Running the docker stack

In the project's root directory, run make new. This pulls the dev-tagged "expungeservice" image and launches the containers using docker-compose. Start and stop the running stack with make up and make down.

After this target completes, you can navigate to http://localhost:3000 in the browser and connect to the React dev server with full hot-module reloading. This may take a minute or two to come up before it is available while it installs node modules. Check the service with make frontend_logs.

In the course of backend development, one may not need to be running the React/HMR dev server. To build the frontend static files, and use Flask to serve them, run the following command:

$ make frontend_down frontend_build

Then navigate to http://localhost:5000 to access the backend service directly. This is configured to serve the static files. make up will start the HMR dev server again at 3000 if you stopped it.

Whenever a dependency is added to the backend, someone needs to rebuild the dev-tagged image and push or folks will get errors when trying to run the stack. To do so, rebuild the image, and reload the backend with:

$ make backend_build backend_reload

If it works, push with:

$ make push

More details in DevOps README.

For more project documentation on Docker, some troubleshooting, and some basic commands, see: doc/docker.md

Cleaning

While in the directory of your local repo, run:

$ make clean

in order to remove build artifacts.

To completely remove containers, volumes, and compose networks, run:

$ make clobber

DevOps

See DevOps README.

Testing

Currently using pytest for testing the backend. Run all backend tests by running the following command in the project root directory:

$ make backend_test

This runs a pytest command to execute all the unit tests inside the backend docker container. All of these tests should pass if you have correctly set up the backend dev environment.

To run a subset of test cases without first shelling into the docker container, you can use a docker-compose exec command, which specifies a container by service name and a runnable command in the container in a single step, e.g.:

$ docker-compose exec expungeservice pipenv run pytest tests/[subdir]

To specify and run a subset of the test cases.

Contributing

Please see CONTRIBUTING.md

Technical Documentation

• Project technical design: doc/design.md
• Additional frontend docs, mostly design patterns: src/frontend/README.md.

License

This project is open source under the terms of the MIT License.