Skip to end of metadata
Go to start of metadata

Data providers and other community stakeholders must currently invest operational and development resources producing search clients to serve a segment of the community. Earthdata Search portals reduce the overhead of providing a search interface similar to Earthdata Search to targeted users. It provides several useful features, including:

  • Running a maintained, up-to-date instance of Earthdata Search without incurring the cost of hardware or administration
  • The ability to present a limited set of collections to users, scoped to only those relevant to the target user community
  • Presentation of additional logos, navigation, and page titles
  • A simple URL for the portal (https://search.earthdata.nasa.gov/portal/your-portal-name) with bookmark-able links within the portal
  • Interoperability with the full Earthdata Search site, allowing users to optionally and easily search the full list of collections, and see their saved projects and past retrievals from the portal in Earthdata Search
  • Inclusion of custom provider-developed CSS and/or Javascript resources into every page to make arbitrary updates to page style and add or remove features

The remainder of this document will walk through the process of creating and configuring a portal.

Step 1: Reach out!

We're here to help, and we want to understand community needs so we can refine our features. Email Valerie Dixon (valerie.dixon@nasa.gov) to get started with your portal and get in touch with developers.

Step 2:  Fork our GitHub repository

Important: The workflow for configuring portals is geared toward teams who have familiarity with basic development tools such as git. If this is not the case for you, please reach out to us and let us know; we may be able to assist you with basic configuration.

Because portal configurations are powerful enough to modify Earthdata Search's functionality in arbitrary ways, we must handle portal configuration through our Github project (https://github.com/nasa/earthdata-search/).  This allows us to understand incoming changes, test existing portals against new features, and prevent insecure or malicious code from entering our operational environment.

To provide us configuration most efficiently, you will need to fork our GitHub repository.

Step 3:  Startup a Local instance of Earthdata Search

Clone the code from your fork and follow the README to get a local instance of Earthdata Search set up.

Step 4: Configure your portal

To create your portal you will need to create a new directory in "/portals" with a unique name you want as your portal identifier, for this example we will use "example". You then will create the config.json file ("/portals/example/config.json"). 

A significant amount of configuration can be done through this config.json file. You can view example configurations at https://github.com/nasa/earthdata-search/tree/master/portals/simple/config.json and https://github.com/nasa/earthdata-search/tree/master/portals/complex/config.json. Here is an explanation of the configuration:

KeyData TypeExplanation
featuresObjectFeature configuration
    advancedSearchBooleanEnable/disable the advanced search feature
    authenticationBooleanEnable/disable all features that rely on authentication (logging in/projects)
    featureFacetsObjectFeature Facet configuration
        showAvailableFromAwsCloudBooleanShow/hide the Available from AWS Cloud feature facet
        showCustomizableBooleanShow/hide the Customizable feature facet
        showMapImageryBooleanShow/hide the Map Imagery feature facet
        showNearRealTimeBooleanShow/hide the Near Real Time feature facet
footerObjectFooter configuration
    displayVersionBooleanDisplay the current application version in the footer
    attributionTextStringText to display in the footer, example "NASA Official: ..."
    primaryLinksArray

Array of links to display on the left side of the footer

This array is made up of objects with two values:

{
    title: "The viewable text of the link", 
    href: "The URL the link will follow"
}
    secondaryLinksArrayArray of links to display on the right side of the footer. This uses the same objects as `primaryLinks`
hasStyles
Boolean

This tells EDSC if it needs to load a "styles.scss" file,  see Advanced Configuration.

hasScripts
BooleanThis tells EDSC if it needs to load a "scripts.js" file, see Advanced Configuration.
logo
Object (Optional)Configuration for a logo to appear to the right of the NASA logo in the upper left of the page. If omitted, no logo will be added.
    id
String (Optional)This is the id attribute of the <a> tag that houses the logo image, see Advanced Configuration.
    image
String (Optional)Path to logo image. This is not recommended, please see Advanced Configuration for the preferred method of adding the logo image.
    link
String (Optional)This is the URL that users will be sent to when clicking on the logo image. If no value is provided clicking on the logo image will return the user to the EDSC portal home (/portal/example/search).
    title
String (Optional)This text is set as the title attribute in the <a> tag that houses the logo image, it will be displayed when you user hovers their mouse over the logo
org
String (Optional)A short string representing the organization that replaces "Earthdata" in the top-left of the site toolbar. If omitted, it will just say "Earthdata."
pageTitleStringThis will appear after the default portal's `org` and `title` in the HTML page title (see in the tab of the browser). For example if EDSC is the default portal then the page title will be "Earthdata Search :: <pageTitle>"
parentConfigStringThe parent config file for this portal. If your portal will be deployed to EOSDIS Earthdata Search this value should be "edsc". If not, set this to "default".
query
Object (Optional)

These parameters are used to filter the list of collections exposed in the portal. 

Current supported values:

  • tagKey
  • dataCenter
  • project
  • hasGranulesOrCwic (set to null to include all collections)
  • echoCollectionId (this narrows the results to a single collection, only used as an example)

One common pattern is to show all the datasets in a dataCenter. This example shows the ORNL DAAC portal configuration:

  "query": {
    "dataCenter": "ORNL_DAAC",
    "hasGranulesOrCwic": null
  },

Likewise, for Science Project-focused portals, here is the AIRMOSS project portal:

  "query": {
    "project": "AirMOSS",
    "hasGranulesOrCwic": null
  },

A more nuanced approach can be applied using tags in CMR.  Here is an example from the Suborbital portal using the tagKey parameter (note that the tagKey can contain simple wildcards):

  "query": {
    "tagKey": ["gov.nasa.impact.*"],
    "hasGranulesOrCwic": null
  },

If you need support of another CMR query parameter, please contact us.

Refer to the CMR documentation for information on parameters:
https://cmr.earthdata.nasa.gov/search/site/search_api_docs.html 

title
String (Optional)

A short string to be used when referring to the portal. This will appear verbatim where the word "Search" is in the top-left of the site toolbar and will appear in various other places as "Example Portal" when referring to the portal. If omitted, a capitalized version of the portal ID will be used, i.e. "Example."

uiObjectUI configurations
    showOnlyGranulesCheckboxBooleanShow/hide the "
    showNonEosdisCheckboxBoolean
    showTophatBooleanShow/hide Tophat

Inheriting Configuration Values

Portals now will inherit configuration values from a parent configuration. See the "parentConfig" value above. This allows you to use all of a parent's config values and keep your portal configuration minimal if your portal needs most of the same features as the parent configuration.

Advanced Configuration

Portals allow authors to provide SASS styles and JavaScript to run on each page within the portal. These can be useful for altering the page style, hiding unnecessary features, or adding new features that do not make sense for inclusion in Earthdata Search. You can do essentially anything that can be done with Javascript or SASS.

If you are authoring something complex or if you have needs that you feel would be better addressed at the basic configuration level, please reach out to our developers, who Chris Lynnes (christopher.s.lynnes@nasa.gov) can put you in touch with.

styles.scss

Setting up a Custom Portal Logo:

This is the preferred way to add a new logo image, which are displayed next to the NASA meatball, centered vertically. You can reference the existing portals in the ./portals/... directory for examples of how this works in practice.

  1. Set hasStyles to true in config.json
  2. Set id, link, and title in the logo section of the config.json
  3. Save your image(s) into the ../portals/myportal/images/ directory
  4. If in In the logo section of your config.json file, you set the "id" field to "example-logo", then you would use this SASS rule to load that image:

    #example-logo {
      height: 25px; // set the correct height for your logo 
      width: 54px // set the correct width for your logo ;
      background-image: url('./images/<portal name>-logo.[png|jpeg]');
    }
Custom Logo Best Practices:
  • Images will be displayed at a maximum of 25px tall by 57px wide. Logos should be trimmed to size as to fit will within those maximum dimensions.
  • Images can be provided at twice their displayed size (50px x 114px maximum) for better display on high resolution screens.
  • Images should be named using the following format: <portal name>-logo.[png|jpeg].
  • If available, versions of the logo with transparent backgrounds (typically png's), meant to be displayed on dark backgrounds are preferred.

scripts.js

This file will load and execute any JavaScript you need in EDSC. Because EDSC is a single page React application, the uses of this file are limited. But, you can use it to pre-load and second version of your logo to be used when the user hovers over the image. To do this refer to https://github.com/nasa/earthdata-search/tree/master/portals/ornldaac/scripts.js and https://github.com/nasa/earthdata-search/tree/master/portals/ornldaac/styles.scss.

In order for this file to be executed, hasScripts must be set to true in config.json

Step 5:  Incorporating Changes into Earthdata Search

When you have made and tested your changes, push them to your forked copy of the Earthdata Search repository and issue a pull request into the main repository using the pull request template. Our developers will review and incorporate the changes as soon as possible.

Our normal progression to operations is as follows:

  1. When a pull request is merged, it starts a build. Within a few minutes of the build becoming green, that changes gets pushed to our SIT environment for testing: https://search.sit.earthdata.nasa.gov
  2. Every other Wednesday, our current UAT environment (https://search.uat.earthdata.nasa.gov) is deployed to our operational environment (https://search.earthdata.nasa.gov) and our SIT environment from the previous Monday is deployed to our UAT environment.

So the progression from a pull request being accepted to it becoming an operational change takes about a month, during which it is available in testing environments.

While we would prefer to stick to this schedule wherever possible, we understand you may have differing schedule needs. If you need it to reach operations sooner, please indicate the desired date on the pull request and we will do our best to accommodate.

  • No labels

4 Comments

  1. (1) How does a curator tag the actual data collections?

    (2) Can we write out the fork and pull request procedures as a step by step recipe that a scientist could understand?

    1. As far as I understand, CMR has not opened up tagging to users because the permissions needed would allow users to tag any collection, not just their own collections. They would also be able to edit/delete tags from other collections as well.

      I think that CMR does have stories to improve the permissions granularity, but that would need to be prioritized.

      1. I'm not thinking of end users. I am thinking of DAAC support scientists, NASA applications scientists, etc. who are on the front lines of dataset curation for EOSDIS' various communities.

  2. Patrick Quinn please add a table of contents so I can link to Subsections. Thank you.