This project is idle. Please reach out to OpenOakland if you would like to learn more.
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.
- Code of conduct and values
- Quickstart for developers and designers
- Contributing as a non-developer
- Project documentation
- Contact
- License
To participate in this project, we ask you to abide by the OpenOakland Code of Conduct, and honor the 17 Principles of Environmental Justice.
Once you download the WOAP codebase from GitHub, there are two methods to allow you to run the application locally in your browser.
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.
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.
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.
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
- If you get no response, Node.js is not yet on your system; see Node Downloads to download and install Node.js and the Node Package Manager (NPM).
- If you get a number lower than 16.14.0, please upgrade to the version recommended for our project:
nvm install 16.14.0 - If you get a number higher than 16.14.0, you may wish to switch to this version:
nvm use 16.14.0See above to install if necessary. - If you get a response of 16.14.0, you have the correct version of Node.js and NPM installed; continue below.
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.
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.
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}
cd {directory path, e.g. web/src}
Make desired changes to files in /src folder
git add .
Don't forget that period!
git commit -m "{message text}"
git push origin {new-branch-name}
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).
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
- woaq-proxy: nginx-proxy, ssl-autogen
- woaq-web: typescript, react, razzle, semantic UI
- woaq-api: python, django-rest-framework
- woaq-db: postgis
With Docker installed and WOAP instances running, you can now open your web browser and access the services at the following lvh domains:
- Homepage: lvh.me
- API: api.lvh.me
- API Documentation: api.lvh.me/swagger
Follow testing and linting instructions in the Pull Request Template
We use Trello for project management (note that after February 2022, this may change):
- Review and add a comment to any light blue “Design & Research” card currently sitting in the In QA column. Or;
- Grab any card tagged with the light blue “Design & Research” label in the Ready to Work On column and get started.
We use Trello to document and discuss data decisions (note that after February 2022, this may change):
- Review and add a comment to any yellow “Data Q” card currently sitting in the Qs About Data Analysis column. Or;
- Add a new yellow “Data Q” card to the Qs About Data Analysis column for any new questions you think of that might be important to answer.
- Email: woaq@openoakland.org
- Slack: #WOAQ channel (complete this form for access)
- In person: Join us Tuesday evenings at Oakland City Hall.
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).