Earthdata Pub Forms

This is the Forms code repository for Earthdata Pub (EDPub).

Table of Contents

• Earthdata Pub Forms
  • Table of Contents
  • Contributing
  • Installing
  • Running locally
    • Dashboard and API
  • Styling
  • Developing
    • Edits to code
    • Vue builds inside Docker
  • Testing
  • Deploying
  • Documentation

Contributing

See CONTRIBUTING.md for instruction for contributing to the EDPub project. Be sure to read that before submitting pull requests.

Installing

EDPub Forms use node v18.14.1. EDPub Forms use npm version 9.3.1. To build/run the Forms on your local machine, install nvm following the nvm Install & Update Script instructions.

We use npm for local package management, to install the requirements:

nvm install v18.14.1
nvm use
npm install

Running locally

To start and build all containers (api, dashboard, forms and overview):

npm run start-dev

The most current branch of each repo is the 'develop' branches.

You can navigate to 'http://localhost:8080/docs' to verify the api is running.

You can navigate to 'http://localhost:3000' to verify the dashboard is working. Log in initially by choosing 'Earthdata Pub System'.

After being authenticated, you can test forms is working by navigating to 'http://localhost:8081'.

Finally, test that the overview is working by clicking the forms 'Overview' link in the header.

You can spin down all containers, by running this command:

npm run stop-dev

If forms was ever previously opened, you may need to clear the localStorage in the browser. (Do this if the page is blank).

To run forms locally:

npm run start-forms-dev

The vue app can also be run locally using:

npm use
npm install
npm run build
npm run serve

To view logs from the Docker container:

npm run view-logs

Dashboard and API

The Forms application is dependent on the EDPub Dashboard and API. Follow instructions in each repo or the EDPub core repo.

The Dashboard will available at http://localhost:3000/

The API Swagger documentation will available at http://localhost:8080/docs/

Styling

EDPub uses EUI styling.

Developing

Docker setup inspired by https://daten-und-bass.io/blog/getting-started-with-vue-cli-on-docker/

Earthdata Pub Forms allows for local development without needing a local install of node.js, npm, and vue requirements by using Docker to serve the vue.js application. docker-compose makes container deployment simple. See the Dockerfile and docker.compose.yml for details.

To deploy using docker-compose:

docker-compose up

Edits to code

The vue.js application code base is mounted into the Docker container as a volume. This allows the code to be edited outside of the container while vue updates what is served within the container.

Vue builds inside Docker

The Docker container can be entered to run npm or vue commands that will persist outside of the container. To enter the container:

docker exec -it forms_forms_1 /bin/bash

You can run vue run build or other commands.

Testing

Earthdata Pub uses Cypress for e2e testing. The getting started guide was followed.

For setup, follow the instructions in the getting started guide. You may have a few system libraries to install.

Next view cypress.json to make sure your local dev settings match. To run the overview app locally along with testing, run:

npm run start-forms-dev
npm run start-overview-dev

After that it is done:

npm run cypress OR npx cypress open 

The last command will open cypress tests in browser mode. To run in headless mode:

npm run cypress-headless OR npx cypress run OR cypress-headless-all (for all browsers supported)

Firefox does not have a bypass for CORS, so at the time of this writing, the browsers cypress tests can be run on are chrome, chromium, edge, and electron. Cypress says firefox needs to add the equivalent CORS bypass like cypress.json/chromeWebSecurity.

Deploying

Earthdata Pub Forms deploys to AWS using Terraform through Bamboo. In the case that Bamboo is not available, follow instructions in terraform/README.

Documentation

Vuese auto documentation scrapes the javascript comments out of vue files and mixin file and builds markdown files for them. It creates the folder, 'autodocs', as depicted by it's config file .vueserc.

Documentation about Vuese can be found at their NPM page.

To build documentation:

install:

npm install -g @vuese/cli 

or

yarn global add vuese

then build:

npm run build-docs

then serve:

npm run open-docs

It will launch a document server and automatically open the browser.