SARtale Guide

Deploying

The site is published to GitHub Pages by a workflow. Lake requests, accepts and weekly data refreshes run as GitHub Actions too, so there is no server to run. The live site is ml-dev-hub.github.io/SARtale and this guide is at /guide/. The repository belongs to the ML-Dev-Hub organization on GitHub, so Pages serves it at ml-dev-hub.github.io/SARtale. A copy of this repository under another account is served at that account's own address.

One-time owner setup#

Do these three things once on GitHub, in this order, before anyone opens a lake request.

  1. Turn on Pages. Settings → Pages → Source: GitHub Actions.
  2. Create the earthdata environment.
    1. Settings → Environments → New environment, named earthdata.
    2. Deployment branches: Selected branches, then add main.
    3. In that environment, add the secrets EARTHDATA_USERNAME and EARTHDATA_PASSWORD (your free NASA Earthdata login).
    4. Delete any repository-level copies of those secrets: Settings → Secrets and variables → Actions. Then only the rebuild jobs, which run on main, can read them.
  3. Create the labels. Actions → Lake requests → Run workflow once, to create the labels. Do this before any request is opened: the issue form drops a label that does not exist yet, so the first request would carry no lake-request label and no workflow would see it.

The repository's default workflow permissions (Settings → Actions → General) can stay at Read repository contents. Every workflow declares the permissions it needs.

Public repository. The repository is public at ML-Dev-Hub/SARtale, so anyone signed in to GitHub can open a lake request.

The workflows#

FileRunsDoes
deploy.ymlOn every push to main, and by handRuns the app tests, builds the app, copies this guide to /guide/ and publishes to GitHub Pages
lake-request.ymlOn issue events, daily at 04:17 UTC, and by handChecks every lake-request issue, counts NISAR passes, comments, labels, closes invalid ones, updates requests.json and restarts waiting approvals one at a time
lake-accept.ymlWhen a team member adds acceptedRebuilds with the added lake, then commits the data, redeploys, comments and closes the issue. See Lake requests
refresh.ymlMondays at 03:00 UTC, and by handRebuilds all lakes from NISAR and commits only if the data changed

The two rebuild jobs (in lake-accept.yml and refresh.yml) use the earthdata environment and have read-only access. A separate publish job has the write token and no Earthdata login.

Weekly refresh#

New NISAR passes arrive all the time. Each Monday refresh.yml searches, fetches and builds every lake and runs the tests. If the data changed it commits them, and the commit redeploys the site. You can also start it from Actions → Weekly data refresh → Run workflow.

Each rebuild saves a cache entry of about 780 MB; GitHub keeps 10 GB per repo and evicts the oldest, so roughly the last dozen rebuilds are cached.

Scheduled runs can pause. On a public repository GitHub pauses scheduled workflows after 60 days without repository activity. The weekly refresh and the daily request check then stop until someone pushes a commit or turns them on again in the Actions tab.

Check a build locally#

npm --prefix app ci
npm --prefix app run build      # writes app/dist/
npm --prefix app run preview

The build uses relative paths, so it also works from a sub-folder such as /SARtale/. Another static host can serve the contents of app/dist/, but the request form would still open issues on GitHub, and the workflows would still run there.

Updating the data by hand#

After running the pipeline yourself, commit app/public/data/lakes.json and the changed pictures to main. The deploy workflow rebuilds and publishes the site. The app reads the data at start-up, so nothing else needs to change.