Skip to content

Restructure README and add per-audience setup + security docs#57

Merged
rajeeja merged 2 commits into
mainfrom
rajeeja/docs-restructure-security
Jun 8, 2026
Merged

Restructure README and add per-audience setup + security docs#57
rajeeja merged 2 commits into
mainfrom
rajeeja/docs-restructure-security

Conversation

@rajeeja

@rajeeja rajeeja commented Jun 8, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • New top-level README with a "Pick your path" router (local / connect to existing HPC endpoint / stand up new endpoint) and a 5-step local install. Stops at "want HPC?" and links out.
  • New SECURITY.md with a three-audience threat model: local, remote-as-user, remote-as-operator. The operator section includes concrete payload-on-disk impact (verified against a real NCAR endpoint) and a hardening checklist.
  • New docs/remote-hpc.md for HPC users connecting to an existing Globus Compute endpoint. Prereqs pinned at the top, 5 numbered steps with time estimates, troubleshooting table at the bottom.
  • New docs/operating-an-endpoint.md for the person standing up the endpoint. 8 numbered steps including a service-account request email template, Slurm and PBS configs, MEP allowlist path, and day-2 ops.

Why

Today users have to read 7+ overlapping files to figure out which path applies to them, and security guidance is scattered. This PR establishes three front doors keyed to who the reader is, leaves the existing site-specific quickstarts (chrysalis/improv/ucar) in place, and gives sysadmins a single page to send to support.

Test plan

  • `uv run pre-commit run --all-files` (clean)
  • `uv run pytest tests/ --ignore=tests/test_remote_agent.py` (293 passed)
  • Render the new pages on GitHub to confirm tables/blockquotes look right
  • Follow-up: consolidate `docs/getting-started.md`, `docs/hpc.md`, `docs/globus-compute.md` (now superseded) — separate PR

Notes

  • Existing files in `docs/` are untouched to avoid breaking external links. Consolidation in a follow-up.
  • `uv.lock` was repeatedly being touched with a stray 0.1.0 → 0.1.1 bump by `uv run`; explicitly checked-out to keep this PR docs-only.

rajeeja added 2 commits June 8, 2026 17:11
- README rewritten with a "Pick your path" router and a 5-step local install;
  links out to the new remote-hpc / operating-an-endpoint / SECURITY pages
  instead of mixing all audiences into one file.
- SECURITY.md: threat model split into local, remote-as-user, and
  remote-as-operator with concrete payload-on-disk impact and a hardening
  checklist (chmod, MEP allowlist, high-assurance auth, service-account
  migration).
- docs/remote-hpc.md: step-by-step for users who already have an HPC account
  and need to connect to an existing Globus Compute endpoint, with prereqs
  pinned at the top and a troubleshooting table.
- docs/operating-an-endpoint.md: step-by-step for the person standing up the
  endpoint, including a service-account request template, Slurm/PBS configs,
  the MEP allowlist path, and day-2 ops.
Sphinx -W build couldn't resolve ../SECURITY or ../README because those
files are outside the docs/ source root. Switched repo-root cross-refs to
absolute GitHub URLs, which render correctly both on GitHub and in the
Sphinx HTML output. Also added the two new pages to the User Guide toctree.
@rajeeja rajeeja merged commit e20a86a into main Jun 8, 2026
9 checks passed
@rajeeja rajeeja deleted the rajeeja/docs-restructure-security branch June 8, 2026 22:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant