host our own gridlook dashboard

[eeholmes]

Deploy GridLook to GitHub Pages (mostly unchanged fork)

Goal

Host a mostly unchanged copy of GridLook on GitHub Pages so we can run our own dashboard instance (e.g., for NOAA / research datasets) while continuing to use upstream functionality.

This deployment assumes:

• GridLook is a static frontend (Vite + Vue)
• Datasets are public and CORS-enabled
• Zarr v3 datasets will include consolidated metadata at release time

No backend server is required.

---

Overview

Deployment flow:

Fork repo
Clone locally
Verify local dev works
Add GitHub Pages workflow
Push to main
Enable Pages
Access dashboard

Result:

https://<org-or-user>.github.io/<repo-name>/

---

Step 1 — Fork the repository

Fork:

https://github.com/d70-t/gridlook

Then clone your fork:

git clone https://github.com/<your-org-or-user>/gridlook.git
cd gridlook

---

Step 2 — Verify local build works

Install dependencies:

npm install

Run development server:

npm run dev

Expected:

http://localhost:3000

You should see the GridLook UI.

---

Step 3 — Build the static site

npm run build

This creates:

dist/

That directory is what GitHub Pages will host.

---

Step 4 — Add GitHub Pages deployment workflow

Create:

.github/workflows/deploy-pages.yaml

Paste:

name: Deploy GridLook to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build

      - name: Configure Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

Commit and push.

---

Step 5 — Enable GitHub Pages

Go to:

Repository Settings → Pages

Set:

Source: GitHub Actions

That is all.

---

Step 6 — Access your dashboard

After the workflow runs:

https://<org>.github.io/gridlook/

Example:

https://noaa-nwfsc.github.io/gridlook/

---

Using the dashboard

Example dataset URL:

https://storage.googleapis.com/<bucket>/<zarr>

Example full dashboard link:

https://<org>.github.io/gridlook/#https://storage.googleapis.com/<bucket>/<zarr>

---

Requirement: consolidated metadata for published Zarr v3

Browser-based tools perform best when consolidated metadata is present.

Add this to the release workflow, not development.

import zarr
import fsspec

store = fsspec.get_mapper(
    "gcs://bucket/path/to/zarr",
    token="google_default"
)

zarr.consolidate_metadata(store)

Important:

• run after writing the dataset
• run once per release
• safe to repeat
• only updates root zarr.json

---

Optional — backup root metadata before consolidation

Recommended but not required.

import gcsfs
from datetime import date

fs = gcsfs.GCSFileSystem(token="google_default")

store = "bucket/path/to/zarr"

src = f"{store}/zarr.json"
dst = f"{store}/zarr.pre_consolidation.{date.today()}.json"

fs.cp(src, dst)

---

Expected behavior

This deployment should:

• run entirely as a static site
• require no server
• work on GitHub Pages
• behave the same as gridlook.pages.dev
• support consolidated Zarr v3 stores

---

Non-goals

This issue does NOT cover:

• modifying GridLook code
• supporting unconsolidated traversal
• adding authentication
• backend hosting
• dataset generation

---

Maintenance

Keep fork up to date:

git remote add upstream https://github.com/d70-t/gridlook.git
git fetch upstream
git merge upstream/main

---

Summary

We can host our own GridLook instance on GitHub Pages with:

• one workflow file
• no code changes
• static hosting only

This provides:

• stable dashboard URL
• control over deployment
• compatibility with published consolidated Zarr v3 datasets