Home

Awesome

West Oakland Air Quality Project (WOAQ) TravisCI Codecov Code style: black

West Oakland Air Quality (WOAQ) aims to help West Oaklanders fight for better air by making their local air quality data more accessible and meaningful, and providing the digital advocacy tools needed to drive change in their neighborhood.

WOAQ is an OpenOakland project, co-created with the West Oakland Environmental Indicators Project (WOEIP), a community-based environmental justice organization that has been collecting air quality data for over a decade. WOEIP is dedicated to achieving healthy homes, healthy jobs and healthy neighborhoods for all who live, work, learn and play in West Oakland, California.

Readme contents

Code of conduct and values

To participate in this project, we ask you to abide by the OpenOakland Code of Conduct, and honor the 17 Principles of Environmental Justice.

Quickstart for developers and designers

Once you download the WOAP codebase from GitHub, there are two methods to allow you to run the application locally in your browser.

Node.js

The code you download from GitHub does not contain the Node.js libraries needed to run the site locally. You can install Node.js if you don't already have it installed and then run a command to get the needed Node.js libraries. This method allows you to run the front-end but does not install the back-end database. With this method, you can make and submit front-end edits to the project, but you won't be able to upload GPS and datalogger files nor see these data on the map. This is a good method for designers and folks with computers with 4GB or less of available memory.

Docker

Alternatively, you can install Docker which allows creation of virtual machine instances within your computer configured to run the app. Running the Docker configuration files in the WOAP codebase, all four needed instances are created -- the front-end and Node libraries, the database back-end, the API, and the proxy to manage all the connections between them -- allowing you to use the application locally as if you were using it in production, and to make and submit edits to the project. Docker uses more active memory (4GB typically) and disk space (60GB) than running the app with Node.js only. See the Docker requirements for Mac or Windows for more information.

Getting the project code

The starting point for either of the two install methods is to get the current WOAQ project code.

git clone https://github.com/openoakland/woeip.git
cd woeip

This will pull in the current project code from the develop branch and bring you into the installed directory, setting it up with git to allow you to manage versions, push edits, etc.

Next, to start the app, use either Method 1 or Method 2 to get the project running locally.

Starting the app locally with NPM (Method 1)

The current recommendation to avoid compatibilty issues is to use Node.js version 16.14.0. Check to see if already have it installed.

node --version

Once Node.js and NPM are installed, simply do the following to go to the ..\web front-end directory, install all the needed libraries the app requires as listed in package.json, and then open up the app in a web browser locally with a script also defined in package.json

cd web
npm install
npm run start

Your browser should now open, navigating to the app running at http://localhost:3000/. Note that you won't be able to upload data files to the app or see them mapped, but you can see and interact with the front-end. You can now skip down to the section To update the front-end locally to learn about making and submitting changes to the code. See also the section Contributing as a non-developer if preferred.

Starting the app locally with Docker (Method 2)

Install Docker, if needed, then issue the Docker command while in the woeip directory to build the four instances needed to create the app.

docker-compose up -d --build

All the images will start downloading and the containers will start automatically. When complete, you can browse to http://localhost:3000/ to see the running app.

Go to the http://localhost:3000/upload page to upload a pair of data files that you can then view in the map. Load data files from one of the dated folders within the AQ Join Data folder in the WOAQ Google Drive collection. Load a *.csv and a *.log file. Note the date of the collection and then click Save. The Map page should then open showing your loaded data, or use the calendar interface to switch to the date of your uploaded collection.

With Docker Dashboard, you can start and stop the instances as needed. With any restart of the instances, you'll need to load data files again to see them on the map.

To update the front-end locally

After using either of the above two methods to install the code, you can make edits by the following method.

Create and check out new branch based on an existing branch

git status
git checkout {existing-branch, e.g. develop}
git pull origin develop
git checkout -b {new-branch-name}

Navigate to front-end directory

cd {directory path, e.g. web/src}

In text editor

Make desired changes to files in /src folder

Stage, commit and push changes

git add .

Don't forget that period!

git commit -m "{message text}"
git push origin {new-branch-name}

Open pull request (PR) in WOEIP repo

Go to https://github.com/openoakland/woeip/pulls. Create a new pull request to ask that your code be incorporated into the general codebase. Be sure to include a request for review from team member(s).

To access the back-end database

Please refer to the database schema (1/8/2020)

If you have Docker installed and have the WOAQ instances running, you can do the following to access the Postgres database.

docker-compose exec db bash enters the docker container, a mini-linux machine

psql -U postgres logs in to the database that is running on the mini-linux machine

\c woaq enters the woaq database

\dn list all schemas

\dt list all tables

Run any needed SQL commands here, like

SELECT * from air_quality_device;

\q to quit postgres database

exit to exit container and get back to shell

Services

Domains

With Docker installed and WOAP instances running, you can now open your web browser and access the services at the following lvh domains:

Front-end

Back-end

Code Quality Checks

Follow testing and linting instructions in the Pull Request Template

Contributing as a non-developer

Design & research options

We use Trello for project management (note that after February 2022, this may change):

Data science/analysis options

We use Trello to document and discuss data decisions (note that after February 2022, this may change):

Project documentation

Contact

Reporting security issues

Please do not report security issues in public. Instead, send an email to the WOAQ team at woaq@openoakland.org. Or reach out via the #woaq Slack channel (complete this form for access).

License

MIT