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 Chris Lynnes (christopher.s.lynnes@nasa.gov) to get started with your portal and get in touch with developers.
Prerequisites
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. Clone the code from your fork and follow the README to get a local instance of Earthdata Search set up.
Basic Configuration
A significant amount of configuration can be done through the /config/portals.yml file which also contains examples of existing portals. Here is an explanation of the configuration:
| Line | Explanation |
|---|---|
portals: &portals | Portal configuration intended for production should go under this heading |
example: | The unique identifier for your portal. The main place this gets used is the URL. In this case, the portal would be reached at |
org: My DAAC | 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." |
title: Config Example | 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 "Config Example Portal" when referring to the portal. If omitted, a capitalized version of the portal ID will be used, i.e. "Example." |
params: | Optional. CMR URL parameters used to filter the list of collections available in the portal. Keys ("tag-key") are parameter names and values ("org.example.portal") are filter values. Because these may be combined with other filters, values should use the YAML array syntax (prefix with a dash). The example here will only show collections which have been tagged with "org.example.portal" within the portal. If omitted, no filters will be used. Refer to the CMR documentation for information on available parameters: |
logos: | Optional. A list of logos to appear to the right of the NASA logo in the upper left of the page. If omitted, no logos will be added. The "image" and "link" attributes are required for each provided logo. The image attribute is the URL to the logo image, which will appear 50px tall within the portal. The link attribute provides the page to be loaded when the logo is clicked. Other attributes (optional) get placed as attributes on the HTML link, in this case the "title" attribute determines the tooltip provided when users hover over the image. |
scripts: | Optional. A list of of scripts to include on all portal pages. For maintenance, security, and availability reasons, these must be assets packaged by Earthdata Search and cannot be external links. See the "Advanced Configuration" section for information on authoring these scripts. If omitted, no scripts will be included. |
Advanced Configuration
Portals allow authors to provide scripts to run on each page within the portal. These scripts 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, including loading stylesheets. The scripts are placed at the bottom of the <head> element, after all other site scripts, so all site APIs are available at the time of script execution, but the DOM will not yet have been loaded.
Two examples of these scripts may be helpful to authors:
- Example portal script: https://github.com/nasa/earthdata-search/tree/master/edsc/portals/example
This get loaded by the "complex" portal (https://search.sit.earthdata.nasa.gov/portal/complex?cmr_env=ops) and shows how one might inject CSS, HTML templates, and Javascript into a page. - ORNL portal script: https://github.com/nasa/earthdata-search/tree/master/edsc/portals/ornl
This gets loaded on ORNL portals (https://search.sit.earthdata.nasa.gov/portal/carve?cmr_env=ops). It provides CSS to animate the color of the ORNL logo in the upper left
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.
Scripts must output a file called edsc-portal.*.js to the project's edsc/dist directory when the EDSC build process runs `rake assets:precompile`. Though there are many ways to accomplish this, the most straightforward / well-integrated is as follows:
- Fork and clone the EDSC repository as described in "Prerequisites"
- Copy the example portal and rename key files:
cp -R edsc/portals/example edsc/portals/your-portal-name
mv edsc/portals/your-portal-name/src/js/edsc-portal.example.jsx edsc/portals/your-portal-name/src/js/edsc-portal.your-portal-name.jsx
During the course of creating your portal, you will probably also want to rename or remove the files under edsc/portals/your-portal-name/src/css and edsc/portals/your-portal-name/src/html as needs require - Make the following edits:
- edsc/portals/your-portal-name/package.json: Edit to have the correct portal name, author, etc
- config/webpack.config.js: Add a line under the "entry" section with
"edsc-portal.your-portal-name": "./edsc/portals/ornl/src/js/edsc-portal.your-portal-name.jsx"
- Add an entry to config/portals.yml as described above under "Basic Configuration" with the appropriate "scripts" attribute.
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. Our developers will review and incorporate the changes as soon as possible.
Our normal progression to operations is as follows:
- 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
- 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.
Overview
Content Tools