Water Data For The Nation UI

TEST This repo contains the components of Water Data For The Nation:

• wdfn-server: A Flask web application that is used to create server-rendered pages for USGS water data
• assets: Client-side Javascript, CSS, images, etc.

The application has been developed using Python 3.8.x and Node.js 16.x. This is a work in progress.

Install dependencies

Using code.usgs.gov npm package registry

The package, @wma/wdfn-vue-components, has been published on code.usgs.gov and is a dependency of this project. To install this package you will need to set up a personal access token on code.usgs.gov. The personal access token should have "api" scope. See Authenticate to the Package Registry. We recommend that you add the _authToken npm setting in your user's .npmrc. Add the following to ~/.npmrc, substituting your personal access token. Your personal access token should not be put in the repo's .npmrc. That contains the location of the wma scoped registry.

//code.usgs.gov/api/v4/packages/npm/:_authToken=<your personal access token>

You may also need to have the following environment variables set to a bundle that includes all certs for your environment including any corporate proxy cert: NPM_CONFIG_CAFILE and NODE_EXTRA_CA_CERTS.

In addition, if someone has deleted the version that you are using and replaced it with a new build, you will likely get an EINTEGRITY error when using npm install. If this happens, uninstall @wma/wdfn-vue-components and then reinstall as follows:

npm uninstall @wma/wdfn-vue-components
npm install @wma/wdfn-vue-components --save-exact

Installating dependencies using make

The repository contains a make target to configure a local development environment:

make env

To manually configure your environment, please see the READMEs of each separate project.

Development server

To run all development servers in a watch mode at the same time, use the make target:

make watch

... and to run each dev server individually:

make watch-wdfn
make watch-assets

See the specific project READMEs for additional information.

Special Note - 'lookup files'

The waterdataui application uses what we call 'lookup files' to provide the application with information related to things like state and county codes as well as information about agency names and hydrological units. The data for these files is gathered from various web resources by an Amazon Web Services (AWS) Lambda function.

For local development, example lookup files are stored in the repository in the folder wdfn-server/data and they are not automatically updated. Please note, that the files in the wdfn-server/data directory are there for local development; they are not, necessarily, the files used in the deployed versions of the application.

The sample files can be updated to match what is used on deployment by manually downloading a copy of the new files to replace the files in your wdfn-server/data directory. These new files can be committed to Git and updated in the repository.

Run tests

To run all project tests:

make test

Optionally, you can run the Python and JavaScript tests separately.

# from the root directory
# To start the Python tests:
wdfn-server/env/bin/python -m pytest 

# from the assets directory
npm run test:watch # (runs the tests and stays active waiting for changes)
# or
npm run test # (runs the JavaScript tests once, produces a coverage report and shuts down)

If you want to run just a single test file, you can use "--" to add to the npm script. For example:

npm run test:watch -- src/scripts/monitoring-location/selectors/daily-value-time_series-selector.test.js

Debugging JavaScript tests

The line number that Jest produces is not correct but the error message is very descriptive and as well as the description of the test that failed and usually is enough to isolate a failure. However, sometimes running a test in the browser with dev tools is needed to figure out what the error is. The Jest documentation (https://jestjs.io/docs/en/troubleshooting) describes how to do this. We have added an npm script to make this process a little simpler.

npm run test:debug

To debug a single test use '--' after the command to specify a single test file.

Production build

make build

Clean targets

make clean      ; clean build artifacts
make cleanenv   ; clean environment configuration and build artifacts

make supports chaining targets, so you could also make clean watch, etc.

Run a Local Version on a Mobile Device Using Docker

Preliminary Steps

• Make sure Docker is installed on your system (process varies with Operating System)
• Install a 'tunneling' application. LocalTunnel, an npm app is no longer supported and is unreliable. Another free option is http://localhost.run/
• Disconnect from Virtual Private Network (VPN) or USGS network
• Stop any processes using port 5050 (or be prepared to use a different port)

Build Docker Images from Context in DockerFiles

# From the project root directory run
docker build -t assets assets 
# (builds a Docker Image for the Static Assets server named 'assets' 
# using the Dockerfile in the 'assets' directory)

docker build -t waterdataui wdfn-server 
# (builds a Docker Image for the Flask server named 'waterdataui'
# using the Dockerfile in the 'wdfn-server' directory)

Run the Flask Server as a Process in a Docker Container

docker run -p 5050:5050 waterdataui
# (starts the Flask server in Docker container on port 5050
# using the 'waterdataui' Docker image)

Is it working?

When the container is running, the terminal should look something like . . .

[2020-12-04 14:07:25 +0000] [1] [INFO] Starting gunicorn 20.0.4
[2020-12-04 14:07:25 +0000] [1] [INFO] Listening at: http://0.0.0.0:5050 (1)
[2020-12-04 14:07:25 +0000] [1] [INFO] Using worker: sync
[2020-12-04 14:07:25 +0000] [7] [INFO] Booting worker with pid: 7
[2020-12-04 14:07:25 +0000] [8] [INFO] Booting worker with pid: 8
[2020-12-04 14:07:25 +0000] [9] [INFO] Booting worker with pid: 9
[2020-12-04 14:07:25 +0000] [10] [INFO] Booting worker with pid: 10

You should also be able to visit the site on port 5050 (localhost:5050) on a local browser.

You can then use a local tunneling application and follow its instructions on how to connect a mobile device that is using the same network as your computer.

Clean up

When testing is finished, you will want to turn off the Docker container

# run 
docker ps # (shows all Docker containers on your system)
then run
docker stop <the container id> 
# (the container ID will match up an image shown in the 'docker ps' command named 'waterdataui' 
# (which is what you named it earlier))

# If you don't want the images on your system, you can then remove them with 
docker rmi <image name>

Limitations

For each change, you will need to rebuild the Docker image and restart the process -- which isn't optimal.

So this is best reserved for testing implementations that involve touching the screen of the device, especially with multiple touch points. Such implementations cannot be tested with normal emulations.