LearnNewsExamplesServices
Frontmatter
titledocs: add guide for running AI/ChromaDB tooling on Windows via WSL (#7596)
authorAlachi24
stateMerged
createdAtOct 23, 2025, 6:30 AM
updatedAtOct 24, 2025, 4:20 PM
closedAtOct 24, 2025, 4:17 PM
mergedAtOct 24, 2025, 4:17 PM
branchesdev ← docs/setup-x64-wsl-guide
urlhttps://github.com/neomjs/neo/pull/7617
Merged
Alachi24
Alachi24 commented on Oct 23, 2025, 6:30 AM

…inding issues (#7596)

Please make sure to read the Contributing Guidelines:

https://github.com/neomjs/neo/blob/dev/CONTRIBUTING.md

What kind of change does this PR introduce? (check at least one)

  • Bugfix
  • Feature
  • Code style update
  • Refactor
  • Build-related changes
  • Other, please describe:

Does this PR introduce a breaking change? (check one)

  • Yes
  • No

If yes, please describe the impact and migration path for existing applications:

The PR fulfills these requirements:

  • It's submitted to the dev branch, not the main branch
  • When resolving a specific issue, it's referenced in the PR's title (e.g. fix #xxx[,#xxx], where "xxx" is the issue number)

If adding a new feature, the PR's description includes:

  • A convincing reason for adding this feature (to avoid wasting your time, it's best to open a suggestion issue first and wait for approval before working on it)

Other information:

This PR introduces a dedicated setup guide for users on x64 Ubuntu systems who encounter ChromaDB binding issues during AI server setup. It documents the correct environment configuration using Windows Subsystem for Linux (WSL) to ensure full compatibility and prevent installation failures. Closes #7596

✅ What Was Added

  • New documentation file: .github/setup-x64-wsl.md
  • Step-by-step instructions for enabling virtualization, installing Ubuntu via WSL, and configuring VS Code Remote – WSL
  • Notes on common pitfalls (missing virtualization, skipped Ubuntu user setup, etc.)

🎯 Impact

This update ensures smoother onboarding for contributors using x64 systems by:

  • Resolving the chromadb-js-bindings-linux-x64-gnu module error
  • Providing a reliable WSL-based workaround for ChromaDB installation
  • Enhancing documentation clarity for cross-architecture setup support

@tobiu, your review is kindly needed.

tobiu
tobiu commented on Oct 24, 2025, 10:30 AM

Input from Gemini:

✦ Thank you for putting this guide together. It addresses a real pain point for contributors wanting to work with the AI tooling on x64 systems, as highlighted in #7596.

The upstream ChromaDB issue (https://github.com/chroma-core/chroma/issues/5188) confirms this is a bug in their architecture check, so having a solid workaround like this is crucial for now.

However, I have a significant concern with the current framing. The title and introduction position this as a general "Getting Started with Neo on Windows" guide, which implies that WSL is a requirement for any kind of Neo.mjs development on Windows. This is not the case—the framework itself is cross-platform, and this setup is only a temporary workaround for the optional AI tooling that depends on ChromaDB.

To avoid misleading new users who may only want to use the UI framework, we need to re-scope this guide. Could you please make the following adjustments?

  1. PR Title: Change it to something like: docs: add guide for running AI/ChromaDB tooling on Windows via WSL.
  2. Filename: Rename .github/SETUP_X64-WSL_GUIDE.md to .github/AI_TOOLING_WSL_SETUP.md.
  3. Guide Content: Update the title and introduction to clearly state that this guide is a workaround for a known issue in ChromaDB, is specifically for setting up the AI development environment on Windows, and is not a general requirement for using the Neo.mjs framework.

This reframing ensures the guide is accurate and helps the right audience without creating unnecessary barriers for others. The content of the guide is great, it just needs to be presented in the correct context.

Alachi24
Alachi24 commented on Oct 24, 2025, 3:19 PM

Thank you for that feedback, it gave me a good clarity on the issue. I love the suggestion you gave, and I'll rename them as such. @tobiu

Alachi24
Alachi24 commented on Oct 24, 2025, 3:55 PM

@tobiu Update on it has been done, please kindly review

tobiu
tobiu commented on Oct 24, 2025, 4:16 PM

Out of tokens, input from the gemini flash model:

✦ This is an excellent and much-needed guide! It directly addresses the pain point of setting up the AI tooling with ChromaDB on Windows, which has been a significant hurdle for contributors.

I appreciate how thoroughly the previous feedback regarding the scope and framing of the guide was addressed. The content now clearly communicates that this is a workaround specifically for the AI development environment and not a general requirement for all Neo.mjs development on Windows. The detailed step-by-step instructions are very clear and will be incredibly helpful.

My only remaining suggestion is to refine the PR title and the top-level heading of the document to more accurately reflect the specific focus on AI tooling and WSL. While the body of the introduction clarifies this, the initial title could still be misleading. Perhaps something like:

  • PR Title: docs: add guide for running AI/ChromaDB tooling on Windows via WSL (which is already the current PR title)
  • Document Title: # Setting up Neo's AI Development Environment on Windows with WSL or # Guide for Neo.mjs AI Tooling on Windows (WSL)

This can be a follow-up change, as the core content is now in excellent shape.

Great work, Alachi24!

tobiu
tobiu commented on Oct 24, 2025, 4:20 PM

as a follow up item: to also show the guide inside the learning section, we would need to move it e.g. here: https://github.com/neomjs/neo/tree/dev/learn/guides/ai

and add it inside: https://github.com/neomjs/neo/blob/dev/learn/tree.json