recordexpungPDX

A project to automate expunging qualifying criminal records. This project is done in conjunction with the Multnomah County Public Defender's Office. Learn more in the wiki.

This README is covers project installation and getting started as a contributor. For more info:

Project design documentation: doc/design.md

Additional frontend documentation: src/frontend/README.md.

Table of Contents

• Installation
• Running Components
• Testing
• Project Layout
• Contributing
• License

Installation

Our dev environment uses pipenv for maintaining backend dependencies, and npm to develop the frontend. Docker is used to build, test, and deploy the app stack. A postgres database runs as a service within the docker stack, which exposes a connection locally for running test code in pipenv.

1. Fork, and clone the repo.

2. Install Python:

   • Mac

     To install the latest version of Python on Mac run:

     $ brew install python3
     

     note: This will pull the latest version of Python, so when Python 3.8 or greater is released it will install that version.

   • Linux

     • Ubuntu 18.04

       To install Python 3.7 on Ubuntu 18.04 run the command:

        $ sudo apt-get install python3.7 -y
       

     • Ubuntu 16.04

       To install Python 3.7 on Ubuntu 16.04 follow the instructions here.

   • Windows

     To install Python 3.7 on Windows, follow the instructions in this guide..

3. Install Pipenv

   Install the pipenv package manager which also automatically creates and manages virtual environments.

4. Install additional libraries needed for running the backend natively or with pipenv:

   • Mac

     brew install postgresql
     

     Note: this step is only required to meet a dependency for python's psycopg2 package, namely libpq-dev. The dev environment doesn't require a local installation of the database, because the database runs within the docker stack.

     It may be necessary to then run

     export LDFLAGS="-L/usr/local/opt/openssl/lib"
     

     More information on a Mac installation here: https://wiki.postgresql.org/wiki/Homebrew

   • Linux

     sudo apt-get install libpq-dev -y
     

   • Windows

   TBD

5. Install NPM if you don't already have it installed. This link provides instructions on how to install Node.js and NPM

6. Install backend dependencies:

   A Makefile controls installing dependencies, running the Flask app, and removing build artifacts. While in the directory of your local recordexpungePDX repo, install the backend dependencies by running:

   $ make install
   

   Make will read Pipfile and install listed Python packages into a Pipenv virtualenv.

7. Install frontend dependencies

   While in the directory of your local recordexpungePDX repo, enter into your command line and run:

  $ cd src/frontend

  $ npm install

8. Install docker

   • Mac

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

       (click on Get Docker for Mac [Stable])

   • Linux

     • Docker Installation

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

9. Create a local .env file

While in the directory of your local repo, run:

cp .env.example .env

Cleaning

While in the directory of your local repo, run:

$ make clean

in order to remove build artifacts.

Running the Docker stack

Docker provides a fully sandboxed virtual environment from which we will run the app in production. The project stack must be built and run locally for the complete set of tests (discussed below) to pass, because it runs a local instance of the database. While in the directory of your local repo, run:

docker swarm init

This enables docker to run a stack locally and only needs to be run once.

make dev

This command builds the docker images (web server, flask backend, and postgres database) and launches a docker stack running the three services. Verify the backend is serving requests by navigating to http://localhost:5000/api/hello. The frontend can be reached at http://localhost:3000.

Note: running docker requires root access by default. If you try to run this command with sudo it may fail because it messes up pipenv. Be sure to configure docker so you can run it without using sudo (see above).

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

Testing

Currently using pytest for testing. Run all tests with the following command:

$ make test

All of these tests should pass if you have correctly set up the backend dev environment.

Project Layout

.flaskenv: Environment variables read by flask command-line interface via python-dotenv

Makefile: GNU Makefile controlling installing dependencies and running the application

Pipfile: Pipenv file listing project dependencies

config: Project configuration files

doc: Developer-generated documentation

settings.py: python-dotenv configuration file

src: Source dir

src/backend/expungeservice/app.py: Flask application

Contributing

1. Fork the repo on GitHub
2. Clone the project to your own machine. Replacing YOUR-USERNAME with your github username.

 $ git clone https://github.com/YOUR-USERNAME/recordexpungPDX.git

3. cd into recordexpungPDX

 $ cd recordexpungPDX

4. Configure upstream to sync with your fork

 $ git remote add upstream https://github.com/codeforpdx/recordexpungPDX.git

5. Create a branch to work on. Replacing BRANCH_NAME with a descriptive name of the work planned such as update_contributing_doc

  $ git checkout -b BRANCH_NAME

6. Commit changes to your branch (never to master)
7. Push your work back up to your fork

  $ git push

• NOTE: The first time you do git push on your branch it will error with:

 fatal: The current branch BRANCH_NAME has no upstream branch.
 To push the current branch and set the remote as upstream, use

     git push --set-upstream origin BRANCH_NAME

• Copy the output and run it. Then afterwords simply push more commits by running git push.

8. Submit a Pull request

• NOTE: For future contributions be sure to sync master with upstream

  $ git checkout master
  $ git pull upstream master
  $ git checkout -b BRANCH_NAME

Python code should follow the PEP8 standard. Notably:

• module names should be lowercase and run together, e.g. mymodule
• class names should be camel case, e.g. MyClass
• method and variable names should be snake case, e.g. my_method() and my_var

License

TODO: Add license