Document procedure to run Data Browser locally (#7643) by dsotirho-ucsc · Pull Request #7836 · DataBiosphere/azul

dsotirho-ucsc · 2026-03-06T01:24:57Z

Linked issues: #7643

Checklist

Author

¹ when the issue title describes a problem, the corresponding PR
title is Fix: followed by the issue title

Author (partiality)

Added p tag to titles of partial commits
This PR is labeled partial _{or completely resolves all linked issues}
This PR partially resolves each of the linked issues _{or does not have the partial label}

Author (reindex)

Added r tag to commit title _{or the changes introduced by this PR will not require reindexing of any deployment}
This PR is labeled reindex:dev _{or the changes introduced by it will not require reindexing of dev}
This PR is labeled reindex:anvildev _{or the changes introduced by it will not require reindexing of anvildev}
This PR is labeled reindex:anvilprod _{or the changes introduced by it will not require reindexing of anvilprod}
This PR is labeled reindex:prod _{or the changes introduced by it will not require reindexing of prod}
This PR is labeled reindex:partial and its description documents the specific reindexing procedure for dev, anvildev, anvilprod and prod _{or requires a full reindex or carries none of the labels reindex:dev, reindex:anvildev, reindex:anvilprod and reindex:prod}

Author (mirror)

This PR is labeled mirror:dev _{or the changes introduced by it will not require mirroring of dev}
This PR is labeled mirror:anvildev _{or the changes introduced by it will not require mirroring of anvildev}
This PR is labeled mirror:anvilprod _{or the changes introduced by it will not require mirroring of anvilprod}
This PR is labeled mirror:prod _{or the changes introduced by it will not require mirroring of prod}
This PR is labeled mirror:partial and its description documents the specific mirroring procedure for dev, anvildev, anvilprod and prod _{or requires a full mirroring or carries none of the labels mirror:dev, mirror:anvildev, mirror:anvilprod and mirror:prod}

Author (API changes)

This PR and its linked issues are labeled API _{or this PR does not modify a REST API}
Added a (A) tag to commit title for backwards (in)compatible changes _{or this PR does not modify a REST API}
Updated REST API version number in app.py _{or this PR does not modify a REST API}

Author (upgrading deployments)

Ran make docker_images.json and committed the resulting changes _{or this PR does not modify azul_docker_images, or any other variables referenced in the definition of that variable}
Documented upgrading of deployments in UPGRADING.rst _{or this PR does not require upgrading deployments}
Added u tag to commit title _{or this PR does not require upgrading deployments}
This PR is labeled upgrade _{or does not require upgrading deployments}
This PR is labeled deploy:shared _{or does not modify docker_images.json, and does not require deploying the shared component for any other reason}
This PR is labeled deploy:gitlab _{or does not require deploying the gitlab component}
This PR is labeled deploy:runner _{or does not require deploying the runner image}

Author (hotfixes)

Added F tag to main commit title _{or this PR does not include permanent fix for a temporary hotfix}
Reverted the temporary hotfixes for any linked issues _{or the none of the stable branches (anvilprod and prod) have temporary hotfixes for any of the issues linked to this PR}

Author (before every review)

Rebased PR branch on develop, squashed fixups from prior reviews
Ran make requirements_update _{or this PR does not modify Dockerfile, environment, requirements*.txt, common.mk, Makefile or environment.boot}
Added R tag to commit title _{or this PR does not modify requirements*.txt}
This PR is labeled reqs _{or does not modify requirements*.txt}
make integration_test passes in personal deployment _{or this PR does not modify functionality that could affect the IT outcome}
PR is awaiting requested review from a peer
Status of PR is Review requested
PR is assigned to only the peer and the author

Peer reviewer (after approval)

Note that after requesting changes, the PR must be assigned to only the author.

Actually approved the PR
PR is not a draft
PR is awaiting requested review from system administrator
Status of PR is Review requested
PR is assigned to only the system administrator and the author

System administrator (after approval)

Actually approved the PR
Labeled linked issues as demo or no demo
Commented on linked issues about demo expectations _{or all linked issues are labeled no demo}
Decided if PR can be labeled no sandbox
A comment to this PR details the completed security design review
PR title is appropriate as title of merge commit
N reviews label is accurate
Status of PR is Approved
PR is assigned to only the operator and the author

Operator

Checked reindex:… labels and r commit title tag
Checked mirror:… labels
Checked that demo expectations are clear _{or all linked issues are labeled no demo}
Squashed PR branch and rebased onto develop
Sanity-checked history
Pushed PR branch to GitHub

Operator (deploy `.shared` and `.gitlab` components)

Ran _select dev.shared && CI_COMMIT_REF_NAME=develop make -C terraform/shared apply_keep_unused _{or this PR is not labeled deploy:shared}
Ran _select dev.gitlab && CI_COMMIT_REF_NAME=develop make -C terraform/gitlab apply _{or this PR is not labeled deploy:gitlab}
Ran _select anvildev.shared && CI_COMMIT_REF_NAME=develop make -C terraform/shared apply_keep_unused _{or this PR is not labeled deploy:shared}
Ran _select anvildev.gitlab && CI_COMMIT_REF_NAME=develop make -C terraform/gitlab apply _{or this PR is not labeled deploy:gitlab}
Checked the items in the next section _{or this PR is labeled deploy:gitlab}
PR is assigned to only the system administrator and the author _{or this PR is not labeled deploy:gitlab}

System administrator (post-deploy of `.gitlab` component)

Background migrations for dev.gitlab are complete _{or this PR is not labeled deploy:gitlab}
Background migrations for anvildev.gitlab are complete _{or this PR is not labeled deploy:gitlab}
PR is assigned to only the operator and the author

Operator (deploy runner image)

Ran _select dev.gitlab && make -C terraform/gitlab/runner _{or this PR is not labeled deploy:runner}
Ran _select anvildev.gitlab && make -C terraform/gitlab/runner _{or this PR is not labeled deploy:runner}

Operator (sandbox build)

Operator (merge the branch)

~~All status checks passed and~~ the PR is mergeable
The title of the merge commit starts with the title of this PR
Added PR # reference to merge commit title
Collected commit title tags in merge commit title _{but only included p if the PR is also labeled partial}
Pushed merge commit to GitHub
Status of PR is Merged lower
Status of blocked issues is Triage _{or no issues are blocked on the linked issues}

Operator (main build)

Operator (reindex)

Operator (mirroring)

Started mirroring in dev _{or this PR is not labelled mirror:dev}
Started mirroring in anvildev _{or this PR is not labelled mirror:anvildev}
Checked for, triaged and possibly requeued messages in mirror fail queue in dev _{or this PR is not labelled mirror:dev}
Checked for, triaged and possibly requeued messages in mirror fail queue in anvildev _{or this PR is not labelled mirror:anvildev}
Emptied mirror fail queue in dev _{or this PR is not labelled mirror:dev}
Emptied mirror fail queue in anvildev _{or this PR is not labelled mirror:anvildev}

Operator

Propagated the deploy:shared, deploy:gitlab, deploy:runner, API, reindex:partial, reindex:anvilprod, reindex:prod, mirror:partial, mirror:anvilprod and mirror:prod labels to the next promotion PRs _{or this PR carries none of these labels}
Propagated any specific instructions related to the deploy:shared, deploy:gitlab, deploy:runner, API, reindex:partial, reindex:anvilprod, reindex:prod, mirror:partial, mirror:anvilprod and mirror:prod labels, from the description of this PR to that of the next promotion PRs _{or this PR carries none of these labels}
PR is assigned to no one

Shorthand for review comments

L line is too long
W line wrapping is wrong
Q bad quotes
F other formatting problem

codecov · 2026-03-06T01:38:48Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.91%. Comparing base (3aecff8) to head (93856b1).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #7836   +/-   ##
========================================
  Coverage    84.91%   84.91%           
========================================
  Files          161      161           
  Lines        23104    23104           
========================================
  Hits         19619    19619           
  Misses        3485     3485

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

coveralls · 2026-03-06T01:39:32Z

coverage: 85.059%. remained the same
when pulling 93856b1 on issues/dsotirho-ucsc/7643-data-browser-documentation
into 3aecff8 on develop.

achave11-ucsc · 2026-03-09T16:47:51Z

+and launch a local version of the Data Browser server. On macOS or Linux, a
+specific Node.js version can be installed using the Node.js version management


Suggested change

and launch a local version of the Data Browser server. On macOS or Linux, a

specific Node.js version can be installed using the Node.js version management

and launch a local version of the Data Browser's server. On macOS or Linux, a

specific Node.js version can also be installed using the Node.js version management

achave11-ucsc · 2026-03-09T17:02:11Z

+For example, to locally run a Data Browser for the `dev` deployment and `hca`
+atlas, open `.gitlab/sites/dev/hca/base.yaml` and note the variables
+`data_browser_build_script` and `data_browser_build_env`. The values of these
+variables, `build-ma-dev:hca-dcp` and `ma-dev` respectively, indicate that the
+site config used is `.site-config/hca-dcp/ma-dev/config.ts`, and additionally
+that the argument to specify in the `npm run` command is the one found in
+`package.json` that references `./scripts/dev.sh hca-dcp ma-dev`. Note, it may
+be possible that no such argument can be found, in which case you can
+temporarily create a new argument by adding a line to `package.json` using one
+of the existing lines that mentions `scripts/dev.sh` as a guide.


This could benefit from being broken down into enumerated, concise steps.

achave11-ucsc · 2026-03-09T17:02:23Z

+Use the steps above to first locate the `base.yaml` file for a GitLab colocated
+with your personal deployment, and then open the related `config.ts` site config
+file. After setting `CATALOG` and `DATA_URL` to values appropriate for your
+personal deployment, open `packages.json` to find (or add) the correct argument


Suggested change

personal deployment, open `packages.json` to find (or add) the correct argument

personal deployment, open `package.json` to find (or add) the correct argument

achave11-ucsc · 2026-03-09T17:03:54Z

+personal deployment, open `packages.json` to find (or add) the correct argument
+to use, and then specify that argument in the `npm run` command.
+
+Note that when run locally, the Data Browser might make duplicate requests to


Suggested change

Note that when run locally, the Data Browser might make duplicate requests to

Note that when run locally, the Data Browser will make duplicate requests to

If it doesn't is because StrictMode isn't enabled, no?

dsotirho-ucsc · 2026-03-11T17:37:18Z

7836_IT_2026-03-11.txt

achave11-ucsc · 2026-03-12T15:43:07Z

+3. If no such line can be found in `/package.json`, you can temporarily add one
+using one of the existing lines that mention `dev.sh` as a guide. Be sure to
+give the new line a unique key.
+4. Run `npm run KEY`, where `KEY` is the key of the line you found, or added.


Naming convention of variables should be consistent.

Suggested change

4. Run `npm run KEY`, where `KEY` is the key of the line you found, or added.

4. Run `npm run {key}`, where `{key}` is the key of the line you found, or added.

achave11-ucsc · 2026-03-12T15:48:21Z

+2. Locate and open `/.site-config/FOO/BAR/config.ts`, where `FOO` is the second
+part of the `data_browser_build_script` value, and `BAR` is the
+`data_browser_build_env` value.


Consistency

Suggested change

2. Locate and open `/.site-config/FOO/BAR/config.ts`, where `FOO` is the second

part of the `data_browser_build_script` value, and `BAR` is the

`data_browser_build_env` value.

2. Locate and open `/.site-config/{foo}/{bar}/config.ts`, where `{foo}` is the second

part of the `data_browser_build_script` value, and `{bar}` is the

`data_browser_build_env` value.

achave11-ucsc · 2026-03-12T15:49:01Z

+4. Open `/package.json`, and under the `scripts` section, find (or add) a line
+that mentions `dev.sh` and the values obtained in step 1 (e.g. `hca-dcp` and
+`ma-dev`).
+5. Run `npm run KEY`, where `KEY` is the key of the line you found, or added.


Same

Suggested change

5. Run `npm run KEY`, where `KEY` is the key of the line you found, or added.

5. Run `npm run {key}`, where `{key}` is the key of the line you found, or added.

dsotirho-ucsc · 2026-03-12T18:54:50Z

7836_IT_2026-03-12.txt

achave11-ucsc

Otherwise looks good!

Also, you may want to drop the quotes on "[n]", makes it sound like the name of the tool is [n].

achave11-ucsc · 2026-03-13T03:07:37Z

+(`hca-dcp`) that is needed for our purposes.
+3. Open `/package.json`, and under the `scripts` section, find the key of a
+value that mentions `dev.sh hca-dcp ma-dev`, which is the script used when
+running the Data Browser locally, and the two values obtained in step 1.


Suggested change

running the Data Browser locally, and the two values obtained in step 1.

running the Data Browser locally, and the two values obtained in step 2.

dsotirho-ucsc · 2026-03-16T22:10:05Z

Also, you may want to drop the quotes on "[n]", makes it sound like the name of the tool is [n].

The square brackets are for the markdown. When rendered it looks like:

dsotirho-ucsc · 2026-03-16T23:36:40Z

7836_IT_2026-03-16.txt

achave11-ucsc

Approved ✅

dsotirho-ucsc · 2026-03-17T01:16:17Z

7836_IT_2026-03-16.txt

hannes-ucsc · 2026-03-18T00:17:32Z

dsotirho-ucsc self-assigned this Mar 6, 2026

dsotirho-ucsc linked an issue Mar 6, 2026 that may be closed by this pull request

Document procedure to run Data Browser locally #7643

Closed

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7643-data-browser-documentation branch from 9584ac5 to b09e10a Compare March 6, 2026 19:08

dsotirho-ucsc assigned achave11-ucsc Mar 6, 2026

dsotirho-ucsc requested a review from achave11-ucsc March 6, 2026 19:36

achave11-ucsc requested changes Mar 9, 2026

View reviewed changes

achave11-ucsc removed their assignment Mar 9, 2026

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7643-data-browser-documentation branch from b09e10a to 33e7518 Compare March 11, 2026 16:56

dsotirho-ucsc requested a review from achave11-ucsc March 11, 2026 17:37

dsotirho-ucsc assigned achave11-ucsc Mar 11, 2026

achave11-ucsc requested changes Mar 12, 2026

View reviewed changes

achave11-ucsc removed their assignment Mar 12, 2026

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7643-data-browser-documentation branch from 33e7518 to 52685d8 Compare March 12, 2026 17:59

dsotirho-ucsc requested a review from achave11-ucsc March 12, 2026 18:55

dsotirho-ucsc assigned achave11-ucsc Mar 12, 2026

achave11-ucsc requested changes Mar 13, 2026

View reviewed changes

achave11-ucsc removed their assignment Mar 13, 2026

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7643-data-browser-documentation branch from 52685d8 to c7ce9c4 Compare March 16, 2026 22:06

dsotirho-ucsc requested a review from achave11-ucsc March 16, 2026 23:36

dsotirho-ucsc assigned achave11-ucsc Mar 16, 2026

achave11-ucsc previously approved these changes Mar 16, 2026

View reviewed changes

achave11-ucsc marked this pull request as ready for review March 16, 2026 23:38

achave11-ucsc requested a review from hannes-ucsc as a code owner March 16, 2026 23:38

achave11-ucsc assigned hannes-ucsc Mar 16, 2026

achave11-ucsc removed their assignment Mar 16, 2026

hannes-ucsc requested changes Mar 16, 2026

View reviewed changes

Comment thread README.md

hannes-ucsc added the 1 review [process] Lead requested changes once label Mar 16, 2026

hannes-ucsc removed their assignment Mar 16, 2026

dsotirho-ucsc dismissed achave11-ucsc’s stale review via c01b929 March 17, 2026 00:41

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7643-data-browser-documentation branch from c7ce9c4 to c01b929 Compare March 17, 2026 00:41

dsotirho-ucsc requested a review from hannes-ucsc March 17, 2026 01:16

dsotirho-ucsc assigned hannes-ucsc Mar 17, 2026

hannes-ucsc approved these changes Mar 18, 2026

View reviewed changes

hannes-ucsc added the no sandbox [process] PR will not be tested in the sandbox label Mar 18, 2026

hannes-ucsc removed their assignment Mar 18, 2026

Document procedure to run Data Browser locally (#7643)

93856b1

dsotirho-ucsc force-pushed the issues/dsotirho-ucsc/7643-data-browser-documentation branch from c01b929 to 93856b1 Compare March 18, 2026 17:26

hannes-ucsc merged commit bdd3f67 into develop Mar 18, 2026
8 checks passed

dsotirho-ucsc deleted the issues/dsotirho-ucsc/7643-data-browser-documentation branch March 18, 2026 21:10

dsotirho-ucsc removed their assignment Mar 18, 2026

		and launch a local version of the Data Browser server. On macOS or Linux, a
		specific Node.js version can be installed using the Node.js version management

	personal deployment, open `packages.json` to find (or add) the correct argument
	personal deployment, open `package.json` to find (or add) the correct argument

	Note that when run locally, the Data Browser might make duplicate requests to
	Note that when run locally, the Data Browser will make duplicate requests to

	4. Run `npm run KEY`, where `KEY` is the key of the line you found, or added.
	4. Run `npm run {key}`, where `{key}` is the key of the line you found, or added.

	5. Run `npm run KEY`, where `KEY` is the key of the line you found, or added.
	5. Run `npm run {key}`, where `{key}` is the key of the line you found, or added.

	running the Data Browser locally, and the two values obtained in step 1.
	running the Data Browser locally, and the two values obtained in step 2.

Conversation

dsotirho-ucsc commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Author

Author (partiality)

Author (reindex)

Author (mirror)

Author (API changes)

Author (upgrading deployments)

Author (hotfixes)

Author (before every review)

Peer reviewer (after approval)

System administrator (after approval)

Operator

Operator (deploy .shared and .gitlab components)

System administrator (post-deploy of .gitlab component)

Operator (deploy runner image)

Operator (sandbox build)

Operator (merge the branch)

Operator (main build)

Operator (reindex)

Operator (mirroring)

Operator

Shorthand for review comments

Uh oh!

codecov Bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coveralls commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc commented Mar 11, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc commented Mar 12, 2026

Uh oh!

achave11-ucsc left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsotirho-ucsc commented Mar 16, 2026

Uh oh!

dsotirho-ucsc commented Mar 16, 2026

Uh oh!

achave11-ucsc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dsotirho-ucsc commented Mar 17, 2026

Uh oh!

hannes-ucsc commented Mar 18, 2026

Security design review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

dsotirho-ucsc commented Mar 6, 2026 •

edited

Loading

Operator (deploy `.shared` and `.gitlab` components)

System administrator (post-deploy of `.gitlab` component)

codecov Bot commented Mar 6, 2026 •

edited

Loading

coveralls commented Mar 6, 2026 •

edited

Loading

achave11-ucsc left a comment •

edited

Loading