Add placeholder landing page for Nebari Ray Serve Pack by killua156 · Pull Request #12 · nebari-dev/rayserve-pack

killua156 · 2026-05-19T03:52:39Z

Added a placeholder landing page for the Nebari Ray Serve Pack documentation. Content will be filled in a follow on issue.

Closes #11

- Add package.json for Docusaurus configuration and dependencies. - Create sidebars.js for automatic sidebar generation. - Add custom CSS for theming and styling. - Include .nojekyll file to prevent Jekyll processing on GitHub Pages. - Add favicon and logo SVG for branding. - Create tsconfig.json for TypeScript support. - Remove outdated index.md from website/docs.

…user guide structure

- Replace placeholder Docusaurus logo and favicon with the official Nebari mark (from nebari-dev/nebari-docs). - Resolve TBD placeholders in the end-user guide: drop the unbuilt "realistic example" block, replace the dashboard-screenshot TBD with a prose walkthrough, and replace the external-hostname placeholder with operator handoff guidance. - Tighten Ray Serve terminology: clarify that serve.delete removes an application (with all its deployments), not a single @serve.deployment. - Reword the Envoy redirectURI warning so it no longer overstates the upstream behaviour (the gateway does not "reject /"; a bare / just cannot serve as the OAuth callback). - Add troubleshooting for crashlooping Serve replicas (ImportError, OOMKilled, CUDA OOM) so end users have a recovery path. - Rename "Going to production" to "Handing off to production" and link to the operator-side detail in deploying-ray-serve.md instead of duplicating it. - Add a one-line gloss for the RayService CRD on first mention and clarify that deployed applications persist when the notebook closes.

The site has no .ts or .tsx files, so the TypeScript tooling shipped by the Docusaurus scaffold has nothing to act on. Drop: - docs/tsconfig.json (described in its own comment as "not used in compilation, just for editor experience") - the typecheck npm script (would compile nothing) - the TypeScript-only devDependencies (@docusaurus/module-type-aliases, @docusaurus/tsconfig, @docusaurus/types, typescript) — they can be re-added trivially if anyone introduces TS code later Also fix the docs editUrl: the markdown source lives at docs/docs/, not docs/, so "Edit this page" links previously resolved to a 404.

Reorganise the three-page site into the same Introduction / Get started / How-to guides / Reference structure that nebari-dev/nebari-docs uses, and add the missing content pages so the pack docs maintain a comparable level of depth. Structure: - introduction.mdx (slug: /) — landing page in nebari-docs style, with bold-prefix bullets and a DocCardList for next steps. - get-started/ — index landing + deploy.md (was deploying-ray-serve.md). - how-tos/ — index landing + use.md (was using-ray-serve.md) + new troubleshoot.md consolidating the first-aid index across pages. - references/ — index landing + new values.md (every chart value, type, default, description) + new architecture.md (Kubernetes resources, mermaid diagram, what the operator mutates at runtime). Sidebar: handcrafted, category-with-index-doc pattern matching nebari-docs/docs/sidebars.js. Each top-level group is a clickable category landing. Config: - onBrokenLinks switched from warn to throw — broken links now fail the build instead of leaking past CI. - showLastUpdateTime + sidebarCollapsible + sidebar.hideable + autoCollapseCategories for navigation ergonomics. - Footer "Docs" column refreshed to point at the four new top-level sections. Screenshot placeholders (admonition blocks marked `:::info[Screenshot placeholder]`) added where demos are most valuable: the Ray Dashboard Serve tab, the Keycloak login flow, the NebariApp ready state, and the request-path diagram for external access. Real captures can replace them later without touching layout. Cross-links between the moved files updated to use the new paths. Build passes with onBrokenLinks: throw.

Match the nebari-docs navbar experience: - Add docusaurus-lunr-search plugin for client-side search. The index is built during `npm run build` and consumed at runtime; `npm run start` renders the box but returns no results until the site has been built. Same backend nebari-docs uses, no Algolia account required. - Add explicit colorMode config: `defaultMode: 'light'`, `disableSwitch: false`, `respectPrefersColorScheme: true`. The navbar sun/moon toggle is on by default; making it explicit also picks up the visitor's OS preference on first load.

kcpevey

Please add information on how to build the docs to a README.md in the docs folder. What do I need to install? What do I run to build dynamic docs? What do I run to build static docs like the website will have?
This is a good guide - https://github.com/nebari-dev/nebari-docs/tree/main/docs

I tried to build the docs but it failed with

[ERROR] ValidationError: Invalid options object. Progress Plugin has been initialized using an options object that does not match the API schema.

Did you build these docs?

killua156 · 2026-05-20T06:38:48Z

Please add information on how to build the docs to a README.md in the docs folder. What do I need to install? What do I run to build dynamic docs? What do I run to build static docs like the website will have? This is a good guide - https://github.com/nebari-dev/nebari-docs/tree/main/docs

I tried to build the docs but it failed with

[ERROR] ValidationError: Invalid options object. Progress Plugin has been initialized using an options object that does not match the API schema.

Did you build these docs?

Yes, I build locally before pushing . both npm run start and npm run build ran clean for me in powershell on Node 20.19.5 / npm 10.8.2.

Try:

  cd docs
  rm -rf node_modules package-lock.json
  npm install
  npm run build

Added docs/README.md with install, dev, build, serve, and this troubleshooting note.

- Move docs/.gitignore patterns into root .gitignore, delete docs-level one - Add docs/README.md with install, dev, build, serve, and ProgressPlugin troubleshooting - Strip LLM-style narration from custom.css, docusaurus.config.js, sidebars.js

Mirror the nebari-docs deployment setup: add a root netlify.toml that builds the docs/ workspace and publishes docs/build/ on push to main. Switch package management from npm to yarn (resolutions in place of overrides, yarn.lock replaces package-lock.json) so the toolchain matches nebari-docs. Drop the GitHub Pages baseUrl prefix since Netlify serves at the domain root.

killua156 · 2026-05-21T16:23:32Z

changed the website from using node js to yarn.

Try:
cd docs
yarn install
yarn start
Then http://localhost:3000/.

cc: @kcpevey

kcpevey

I have only reviewed a small portion of this PR, but it needs a good bit of work. Please make the changes suggested and take a closer look at what is written. The end users will not be touching the cluster or the deployment of ray itself. All of those things should be moved into the "deploy" docs. This is a good start, but it needs some work. Also make sure that you have actually run through the end user docs successfully.

Wires in landing-page tile, Keycloak login, healthy Serve tab, and DEPLOY_FAILED Serve tab images captured against a real deployment. Tightens "Step 1 - Prepare your notebook environment" around Nebi as the primary install path (pixi-managed JupyterLab envs have no pip) and documents the manual ipykernel registration step Nebi sometimes skips. Loosens the version-match warning so patch-level differences are no longer presented as fatal. Splits "My model is crashlooping or returning errors" into two distinct failure modes - replica startup failures (DEPLOY_FAILED) vs request-time errors that leave the deployment HEALTHY - since the latter is invisible in the dashboard and the original section conflated both.

killua156 · 2026-05-22T19:22:31Z

The end users will not be touching the cluster or the deployment of ray itself.

Yea I was facing this problem cause I was trying to deploy a ray-cluster and got denied when doing the demo to add pictures. Will make changes according to that

killua156 · 2026-05-22T20:36:17Z

Screenshots added for easier understanding.

Rename how-tos/use.md to use_ray_from_notebook.md and rewrite for the end-user audience. End users on a Nebari cluster do not have kubectl access and never touch the cluster directly; operator content has been removed from the end-user path: - Drop kubectl-based version checks; use ray.__version__ from Python. - Drop the "How the pack is deployed" section (service-name listing, in-cluster k8s diagram); duplicated in references/architecture.md. - Drop the kubectl port-forward in Step 4; point users at the Nebari landing-page Ray tile instead. - Drop Step 5 "Handing off to production" - that workflow needs more thought and is operator-side anyway. - Drop the operator YAML block in "Accessing externally"; keep only the user-facing call flow. - Drop the pip-install fallback in Step 1 - Nebi is the only sensible path on Nebari, and the dual workflow was confusing. - Drop default Ray/Python version numbers (they go stale). - Rewrite troubleshoot recipes to use python/ray API or "ask your operator" instead of kubectl. introduction.mdx: align with Nebari (not generic k8s), drop the "Dask gateway from data-science pack" suggestion (it doesn't exist), drop the "At a glance" table (version numbers go stale), fix behaviour -> behavior, tighten OIDC-auth bullet. Update sidebars.js, how-tos/index.md, get-started/deploy.md, and how-tos/troubleshoot.md to point at the new filename.

- architecture: redraw diagram to show both dashboard and serve NebariApps with correct routing edges; add :6379 GCS port to head pod - use_ray_from_notebook: fix ray.__version__ snippet (was printing local, not cluster version) via a @ray.remote task; on-site link to deploy; network-policy section now routes operators to a real fix - deploy: new operator section for JupyterHub network policy blocking notebook egress, with concrete NetworkPolicy YAML; prerequisites table now has headers; chart-version stamp on configuration - values: drop duplicate Production image block (canonical in deploy); chart-version stamp - introduction: fix dangling modifier and "Kubernetes or Nebari" framing - drop two leaked "Screenshot pending" admonitions

Purple-bordered icon button with rounded corners, matching the Nebari landing-page navbar. Gold sun in dark mode, purple moon in light mode, faint purple wash on hover, magenta outline on keyboard focus.

Captures the stack (Docusaurus + Yarn + Netlify), information architecture (end-user vs operator split, Diataxis mapping), writing conventions, verification habits, ten documented anti-patterns from this repo's review history, pre-publish checklist, demo workflow, reviewer collaboration patterns, and git conventions specific to this repo. Intended as a reusable reference for similar OSS docs projects.

AGENT.md is a Claude/agent-flavored working playbook with references to local tooling that don't generalize to the public repo. Untrack from git (file stays on disk) and add to .gitignore so it doesn't get re-committed.

andrewfulton9

In general looks good. I added a couple of comments. I was able to build and serve locally

killua156 · 2026-06-11T03:46:46Z

Suggested changes made.

- docusaurus.config.ts, sidebars.ts, tsconfig.json with typecheck script - Align deps with nebi: Docusaurus 3.10.1, React 19, @docusaurus/faster, @easyops-cn/docusaurus-search-local (drops the webpack pin workaround) - Switch yarn to npm (package-lock.json) - Replace deploy-docs.yml with nebi-style build-only docs.yml

killua156 · 2026-06-12T17:59:39Z

@kcpevey @andrewfulton9 Suggested changes made. Also converted the docs setup to TypeScript and simplified the workflow to a build-only check (matching nebi), same as requested on the chat pack. Ready for another look.

andrewfulton9

One minor comment, but otherwise looks good! I verified that the commands in the README function as expected and the docs can be built and served locally

andrewfulton9 · 2026-06-15T15:32:01Z

+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*


the yarn references here should probably be deleted

andrewfulton9

The the docs workflow also deploy to GH pages?

killua156 · 2026-06-15T17:20:27Z

No, it's a build-only CI check. It doesn't deploy to Pages yet. Should I deploy to gh pages too?

andrewfulton9 · 2026-06-17T20:49:32Z

No, it's a build-only CI check. It doesn't deploy to Pages yet. Should I deploy to gh pages too?

@killua156, yes please do. You can use the below script:

name: Deploy docs to GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: docs/package-lock.json

      - name: Install dependencies
        run: npm ci
        working-directory: docs

      - name: Build website
        run: npm run build
        working-directory: docs

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

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    if: github.ref == 'refs/heads/main'
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

andrewfulton9

LGTM!

killua156 added 5 commits May 14, 2026 23:22

adding files for documentation and website.

69a925f

Update documentation and styles for Nebari Ray Serve Pack

9131f88

fix(docs): update Docusaurus config for markdown path and edit URL

6ef9e7d

feat(docs): enhance documentation for deploying Ray Serve and update …

f33207b

…user guide structure

killua156 marked this pull request as ready for review May 19, 2026 03:54

killua156 added 2 commits May 18, 2026 23:09

killua156 force-pushed the feature-doc branch from fc6a475 to d53af89 Compare May 19, 2026 04:10

killua156 mentioned this pull request May 19, 2026

Add end user documentation #11

Closed

killua156 added 2 commits May 19, 2026 01:54

kcpevey requested changes May 19, 2026

View reviewed changes

Comment thread docs/.gitignore Outdated

Comment thread docs/src/css/custom.css Outdated

killua156 added 2 commits May 20, 2026 01:58

docs: address review feedback

091b705

- Move docs/.gitignore patterns into root .gitignore, delete docs-level one - Add docs/README.md with install, dev, build, serve, and ProgressPlugin troubleshooting - Strip LLM-style narration from custom.css, docusaurus.config.js, sidebars.js

kcpevey reviewed May 22, 2026

View reviewed changes

killua156 added 6 commits May 22, 2026 15:58

docs: style color-mode toggle to match Nebari UI

17b0f8d

Purple-bordered icon button with rounded corners, matching the Nebari landing-page navbar. Gold sun in dark mode, purple moon in light mode, faint purple wash on hover, magenta outline on keyboard focus.

chore: untrack AGENT.md; keep as local playbook only

8a3573d

AGENT.md is a Claude/agent-flavored working playbook with references to local tooling that don't generalize to the public repo. Untrack from git (file stays on disk) and add to .gitignore so it doesn't get re-committed.

docs: replace full docs with placeholder landing page

2e86b91

kcpevey requested changes Jun 9, 2026

View reviewed changes

Comment thread docs/README.md Outdated

docs: remove all Netlify references

b9c17b8

killua156 changed the title ~~Adding documentation landing page for ray serve pack~~ Add placeholder landing page Jun 10, 2026

killua156 changed the title ~~Add placeholder landing page~~ Add placeholder landing page for Nebari Ray Serve Pack Jun 10, 2026

andrewfulton9 reviewed Jun 10, 2026

View reviewed changes

Comment thread docs/README.md Outdated

Comment thread docs/README.md Outdated

Remove note, troubleshooting and deployment boilerplate from docs README

5dbafff

andrewfulton9 approved these changes Jun 15, 2026

View reviewed changes

andrewfulton9 mentioned this pull request Jun 15, 2026

[DOC] - Update docs package manager from yarn to npm nebari-dev/nebi-pack#28

Open

1 task

andrewfulton9 reviewed Jun 15, 2026

View reviewed changes

killua156 requested a review from kcpevey June 17, 2026 16:06

Deploy docs to GitHub Pages and drop yarn gitignore entries

4e126cd

andrewfulton9 approved these changes Jun 18, 2026

View reviewed changes

andrewfulton9 merged commit f89e8dc into nebari-dev:main Jun 18, 2026
4 checks passed

killua156 deleted the feature-doc branch June 18, 2026 17:26

Uh oh!

Conversation

killua156 commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kcpevey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

killua156 commented May 20, 2026

Uh oh!

killua156 commented May 21, 2026

Uh oh!

kcpevey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

killua156 commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

killua156 commented May 22, 2026

Uh oh!

Uh oh!

andrewfulton9 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

killua156 commented Jun 11, 2026

Uh oh!

killua156 commented Jun 12, 2026

Uh oh!

andrewfulton9 left a comment

Choose a reason for hiding this comment

Uh oh!

andrewfulton9 Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

andrewfulton9 left a comment

Choose a reason for hiding this comment

Uh oh!

killua156 commented Jun 15, 2026

Uh oh!

andrewfulton9 commented Jun 17, 2026

Uh oh!

andrewfulton9 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

killua156 commented May 19, 2026 •

edited

Loading

killua156 commented May 22, 2026 •

edited

Loading