Master
Staging:
** Platform for sale of Christmas tree permits and intake of special use applications for the U.S. Forest Service **
The U.S. Forest Service is engaged in an ongoing effort to modernize and simplify its permitting processes. One facet of this effort is to make special use permits available to obtain online. Flexion worked with GSA's Technology Transformation Service's Office of Acquisitions and the Forest Service to build out this platform for noncommercial and temporary use permits.
The opportunity statement = the problem we are trying to solve with the ePermitting project.
We have the opportunity to modernize the public's ability to apply for special use permits and to purchase permits to harvest Christmas trees. For special use permits, Mt. Baker-Snoqualime is the pilot forest. For Christmas tree permits, Arapaho and Roosevelt, Flathead, Mt. Hood, and Shoshone are the pilot forests. Our belief is that these applications will simplify and speed up the ability to apply for and purchase permits.
- Welcome
- Opportunity Statement
- Table of contents
- Development
- Requirements:
- Clone the repository
- Server development
- Frontend Development
- Install angular cli
- Navigate to frontend directory
- Install dependencies
- Development server
- Build
- Running unit tests
- Running end-to-end tests
- Testing WCAG2AA compliance with pa11y
- Typedoc
- Build typedoc
- Available services
- Pay.gov error mocking in local environment
- Pay.gov in QA environment
- Christmas trees sidebar template
- Docker Environment
- Deployment
- Docs
- Content administration
- Usability testing
- Known technical Debt
- Contributing
- Public domain
There are two options for local development - Docker or installing the dependencies independently.
** The following instructions outline tools and procedures required for local development without docker **
Install yarn package manager
Install Git
All contributors should use git-seekret (https://github.com/18f/laptop#git-seekret) to prevent accidental commits of sensitive data.
Project specific rules are defined on the wiki.
Install Node ^8.9.4
Install PostgreSQL
git clone [repository url] fs-permit-platform
Navigate to cloned repo
cd fs-permit-platform
A running Postgresql database is required in order to run the server locally. Please make sure you have installed Postgresql locally and created a database for this project.
There are environment variables that are required to be set in order to run tests and to run the server in general. Please set up these environment variables either in your shell or on the command line.
View list of required environment variables, and installation instructions
run cd server then run yarn to install dependencies.
To run any of the server commands, either the environment variables above must be available in your shell or on the command line, and you must be in the server directory.
| Function | Command | Additional information |
|---|---|---|
| Setup Database | yarn migrate |
|
| Start the server | yarn dev |
Server is accessible at http://localhost:8080 |
| Revert the last database migration | yarn undoLastMigrate |
|
| Revert all of the database migrations and start with a blank database | yarn undoAllMigrate |
|
| Run eslint for linting | yarn lint |
The linting results will be put into server/lint-results.html. |
| To run all of the tests locally | yarn test |
Be sure your Postgresql server is running |
| To run code coverage locally | yarn coverage |
Be sure your Postgresql server is running. The coverage results can be found in server/coverage/index.html |
With your local Node server running, browse to http://localhost:8080/docs/api in order to view the interactive Swagger API documentation. This documentation will allow interactive access to the API endpoints.
Public users must authenticate with login.gov, and Forest Service admins must authenticate with USDA eAuth. Both of these authentication techniques are handled by the Passport library for Node.js.
Login.gov uses the openid-client passport plugin for the OpenID Connect protocol, and USDA eAuth uses the passport-saml plugin for the SAML protocol.
Due to security restrictions testing can't be done locally, you must use a server on cloud.gov. Setting the PLATFORM environment variable will bypass all authentication checks.
Note: if running in a clustered environment Session Affinity (sticky sessions) should be configured.
Some models (e.g. christmasTreesForests) use a sequelize hook to change the data as configured in the seed commands
at run-time for purposes of testing. An alert is also displayed in the frontend. Mock data application uses the NODE_ENV and environment values in the server and frontend code respectively.
Forest tree cutting start and end dates are saved in the database as a UTC DateTime object. When updating the start and end dates for the forest in the database, you must consider daylight savings, the forest timezone and calculate the offset.
Forest dates on the frontend use the forest's timezone to calculate the correct date and time.
VCAP service value for jwt token is used for appending a token to permit URL to view the purchased permit so that the users cannot easily guess the permit URL.
VCAP service values for Pay.Gov need to be updated for production deploy. {token_url} and {client_url} need to be supplied by Pay.Gov.
To mock Pay.Gov integration use the values in the VCAP example.
The current configuration implements email via google smtp relay. Follow the documentation at https://support.google.com/a/answer/2956491?hl=en to set up your google SMTP relay.
Authentication is set up to support safelisted IP addresses that are allowed to send emails, so no SMTP authentication is required.
The smtpserver value in your VCAP_SERVICES should be smtp-relay.gmail.com
Run yarn global add @angular/cli
cd frontend
Run yarn
Run ng serve for a development server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.
Run ng build --prod --env=prod --aot=false to build the static files for the single paged app. The build artifacts that can be deployed will be stored in the dist/ directory.
Run ng test to execute the unit tests via Karma.
Add --code-coverage flag to print out code coverage statistics.
Run yarn run e2e to execute the end-to-end tests via Protractor.
To run pa11y-ci with the single page angular app with pushstate enabled, you need to first build the static application, and then run the app from a server that supports pushstate. We are using superstatic as our server.
Run pa11y-ci via docker: cd docker; docker-compose up pa11y
Run pa11y-ci without docker: cd frontend; yarn run build-test-pa11y
Install typedoc globally: yarn global add typedoc
cd frontend
build typedoc yarn run docs
typedoc are added to frontend/src/assets/typedoc and are accessible via url at /assets/typedoc/index.html
Navigate to /assets/typedoc/index.html
View services that are available to leverage in components.
-
To mock a pay.gov token error, in the Christmas trees application form, set the first name to 1 and last name to 1.
-
To mock a pay.gov 500 error, in the Christmas trees application form, set the first name to 1 and last name to 2.
-
To mock a pay.gov complete collection error, use credit card number
000000000000XXXX. The last four XXXX represent the pay.gov error code.
- A valid credit card number in staging environment is
4111111111111111.
View instructions to use the Christmas trees sidebar template.
As an alternative to installing all the development tools necessary to run the entire environment on your computer, Docker can be used instead. These instructions will detail how to use Docker to setup a full environment to run the application.
View instructions to get up and running with Docker
View instructions to administer the forest json
Circleci 2.0 is used for continuous integration/deployment. The configuration file for circleci are found at /.circleci/config.yml. An explaination of the checks performed by circleci are found at /wiki/christmas-trees/process/circle-checks.md
The circleci configuration separates the tests into three different jobs that run simultaneously to decrease build time e2e, pa11y tests, and all other tests.
Deployment to a staging server is configured to run on the sprint branch only.
Check the .snyk file under frontend and server for packages ignored by snyk. This
file is managed by the snyk wizard. snyk-protect is run in the Procfile at server start-up.
Deployment to cloud.gov is configured in the .cg-deploy directory. The website's client (frontend) and server (backend) are deployed to separate servers. Each deployment environment (staging, production) require their own manifest files. The manifests are attached to the environment via the deploy script, that authenticates with cloud.gov and pushes the files.
The app/frontend/replace.build.js script is run from circle-ci via config.yml to update the version and date in the transpiled javascript frontend code for each build. This date and version will display in the application footer.
The database is used to store Christmas Trees permit applications for transaction purposes, and a minimal set of variables for each forest that are shared throughout the Christmas trees pages (e.g. on the permit svg and the guidelines.) The Christmas Trees Forests database contains the following fields:
View ChristmasTreesForest database structure
To update a forest’s informational content, you’ll need to find and modify markdown files specific to the forest. The content is structured so that each national forest has its own directory, which can be found under frontend/src/assets/content and then adding the forest_abbr to the url. (For example, frontend/src/assets/content/mthood.) Each forest’s directory contains several markdown files and folders that comprise the bulk of the content for each forest. (For example, /christmas-trees/forests/flathead.)
In the markdown files, database variables are indicated by curly brackets, such as {{treeHeight}}.
View a list of markdown files and their locations
JSON files for forest content are in /assets/config
Each forest has a JSON file that contains any data needed by the forest that does not come from the database or markdown, e.g., shared tree species information. The shared tree species are located in frontend/src/assets/content/common/species.
In order to enable pushstate for single page apps on cloud.gov using the static build pack, you must add a file called Staticfile to the root directory with a single line pushstate: enabled
This allows you to use urls like /some/path instead of /#/some/path
SMTP errors are logged in the console and prefixed with the string NODE_MAILER_SMTP_ERROR. A monitoring service, such as New Relic, can be configured to create alerts when an error with NODE_MAILER_SMTP_ERROR is logged.
While developing we spent time usability testing features with the correct users and applied feedback into the website.
The wiki includes usability testing summaries conducted by Flexion and NCI
The file frontend/src/sass/_focus-fix.scss implements a style fix in the upstream repository: https://github.com/18F/web-design-standards/pull/2112/files Eventually once these changes are released we can remove this file.
The server dependency is JSDOM is currently a fork to pass security vulnerability tests. This should be replaced with the original package once the security vulnerability is fixed.
See CONTRIBUTING for additional information.
This project is in the worldwide public domain. As stated in CONTRIBUTING:
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.