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.
- Turn on Pages. Settings → Pages → Source: GitHub Actions.
- Create the
earthdataenvironment.- Settings → Environments → New environment, named
earthdata. - Deployment branches: Selected branches, then add
main. - In that environment, add the secrets
EARTHDATA_USERNAMEandEARTHDATA_PASSWORD(your free NASA Earthdata login). - 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.
- Settings → Environments → New environment, named
- 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-requestlabel 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#
| File | Runs | Does |
|---|---|---|
deploy.yml | On every push to main, and by hand | Runs the app tests, builds the app, copies this guide to /guide/ and publishes to GitHub Pages |
lake-request.yml | On issue events, daily at 04:17 UTC, and by hand | Checks 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.yml | When a team member adds accepted | Rebuilds with the added lake, then commits the data, redeploys, comments and closes the issue. See Lake requests |
refresh.yml | Mondays at 03:00 UTC, and by hand | Rebuilds 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.
SARtale Guide