docs: improve setup prerequisites and onboarding guidance#1688
docs: improve setup prerequisites and onboarding guidance#1688gouravi19 wants to merge 4 commits into
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly improves the contributor onboarding experience by centralizing setup requirements and providing clear guidance for macOS users. By documenting common pitfalls and resource requirements for local Kubernetes environments, it reduces friction for new contributors and ensures a more reliable development setup. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Docs were sparse and hard to read, / Now the path is clear indeed. / With macOS and Docker set, / The best setup you'll ever get. Footnotes
|
|
Welcome @gouravi19! It looks like this is your first PR to kmesh-net/kmesh 🎉 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request enhances the documentation to support local development on macOS using Docker Desktop and kind. It adds detailed prerequisites, installation instructions for macOS, and a troubleshooting guide for common resource and connectivity issues. Feedback was provided to replace a destructive Docker cleanup command with a safer alternative to prevent accidental data loss.
gouravi19
force-pushed
the
docs/improve-setup-guide
branch
from
52dfbf5 to
48d37f7
Compare
@gouravi19 please fix this markdown linting issues |
Signed-off-by: Gouravi Singh <gouravisingh120@gmail.com>
gouravi19
force-pushed
the
docs/improve-setup-guide
branch
from
48d37f7 to
c059ce7
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (2)
docs/en/kmesh_deploy_and_develop_in_kind.md:169
- There's a stray backtick in this heading. The text reads
`make build` container gets OOMKilled`— there are three backticks total, so the final backtick has no matching opener and breaks the inline code formatting. The closing should likely be afterOOMKilledonly if a matching opening backtick is added (e.g., aroundOOMKilled), or the trailing backtick should be removed.
### 2. `make build` container gets OOMKilled`
CONTRIBUTING.md:59
- This section references a "Kmesh UI", "Headlamp plugins", and "the UI repository" as if these are established parts of the Kmesh project, but a search of the repository finds no such frontend, Headlamp integration, Node.js code, or linked UI repository. Documenting setup steps (e.g., requiring Node.js v18+,
nvm use 18) for a non-existent component is misleading to contributors and likely incorrect. Either the referenced UI/Headlamp integration needs a concrete link to a real repo or component, or these sections (and the related Node.js prerequisite on line 46, the frontend reference in the README, and the UI troubleshooting item inkmesh_deploy_and_develop_in_kind.md) should be removed.
### Frontend and Headlamp UI Setup
If your contributions involve the Kmesh UI or Headlamp plugins:
1. Ensure Node.js v18 or newer is installed (we recommend using `nvm` to manage Node versions).
2. Follow the plugin development instructions in the UI repository. The Kmesh `kind` cluster will serve as the backend data source for the frontend.
| - **Docker Desktop**: Required for local cluster creation. (Ensure you allocate at least 4 CPUs, 8GB RAM, and 20GB disk space). | ||
| - **kind (Kubernetes IN Docker)**: Used to spin up the local cluster. | ||
| - **kubectl**: For interacting with the local cluster. | ||
| - **Node.js (v18+)**: Required if you plan to develop or test the Frontend / Headlamp UI integration. |
| ## Contributing | ||
|
|
||
| If you're interested in being a contributor and want to get involved in developing Kmesh, please see [CONTRIBUTING](CONTRIBUTING.md) for more details on submitting patches and the contribution workflow. | ||
| If you're interested in being a contributor and want to get involved in developing Kmesh, please see [CONTRIBUTING](CONTRIBUTING.md) for more details on submitting patches and the contribution workflow. We fully support local development on macOS via Docker Desktop and `kind`. For detailed setup instructions, including frontend UI setup and troubleshooting, refer to our [Local Development Guide](docs/en/kmesh_deploy_and_develop_in_kind.md). |
| ### 4. UI / Frontend fails to connect to backend | ||
|
|
||
| + **Cause**: Node.js version mismatch or local Kmesh pods are not fully running. | ||
| + **Solution**: Ensure you are using Node.js v18+ (e.g., `nvm use 18`). Verify Kmesh pods are `Running` via `kubectl get pods -n kmesh-system`. | ||
|
|
| Please follow the official guide for your operating system: | ||
| + [Install and Set Up kubectl on Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) | ||
| + **For macOS:** `brew install kubectl` | ||
|
|
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.
Comments suppressed due to low confidence (1)
docs/en/kmesh_deploy_and_develop_in_kind.md:72
- The "Install kubectl" step now contains two redundant "Please follow the official guide" sentences (line 68 introduces it, then line 71 repeats it for Linux). Consider consolidating so the intro line isn't duplicated by the Linux subsection.
Please follow the official guide for your operating system:
**For Linux:**
Please follow the official guide:
[Install and Set Up kubectl on Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
| + **Cause**: Docker Desktop is out of resources. | ||
| + **Solution**: Increase Docker Desktop's resource limits (Settings > Resources). We recommend at least 4 CPUs and 8GB of RAM. | ||
|
|
||
| ### 2. `make build` container gets OOMKilled` |
| **For Linux:** | ||
| Please follow the official guide: | ||
| [Install and Set Up kubectl on Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) | ||
|
|
||
| **For macOS:** | ||
|
|
||
| ```shell | ||
| brew install kubectl | ||
| ``` |
|
|
||
| While Kmesh relies heavily on Linux kernel features (eBPF) for its data plane, **full local development is supported on macOS**. You do not need a Linux machine to contribute. By using Docker Desktop and `kind`, you will run a lightweight Linux VM that fully supports Kmesh's eBPF requirements. | ||
|
|
||
| For detailed steps on setting up this environment (including macOS-specific tips and troubleshooting), please follow the [Kmesh Deploy and Develop in Kind](docs/en/kmesh_deploy_and_develop_in_kind.md) guide. |
| If your contributions involve the Kmesh UI or Headlamp plugins: | ||
|
|
||
| 1. Ensure Node.js v18 or newer is installed (we recommend using `nvm` to manage Node versions). | ||
| 2. Follow the plugin development instructions in the UI repository. The Kmesh `kind` cluster will serve as the backend data source for the frontend. |
| While Kmesh relies heavily on Linux kernel features (eBPF) for its data plane, **full local development is supported on macOS**. You do not need a Linux machine to contribute. By using Docker Desktop and `kind`, you will run a lightweight Linux VM that fully supports Kmesh's eBPF requirements. | ||
|
|
||
| For detailed steps on setting up this environment (including macOS-specific tips and troubleshooting), please follow the [Kmesh Deploy and Develop in Kind](docs/en/kmesh_deploy_and_develop_in_kind.md) guide. | ||
|
|
| ### Prerequisites | ||
|
|
||
| Before you begin, ensure you have the following installed: | ||
|
|
||
| - **Docker Desktop**: Required for local cluster creation. (Ensure you allocate at least 4 CPUs, 8GB RAM, and 20GB disk space). | ||
| - **kind (Kubernetes IN Docker)**: Used to spin up the local cluster. | ||
| - **kubectl**: For interacting with the local cluster. |
|
|
||
| If your contributions involve the Kmesh UI or Headlamp plugins: | ||
|
|
||
| 1. Ensure Node.js v18 or newer is installed (we recommend using `nvm` to manage Node versions). |
Summary
This PR improves contributor onboarding and setup guidance, especially for macOS users and new contributors working with local Kubernetes environments.
Improvements
Motivation
While setting up the project locally, I encountered several onboarding issues related to Docker readiness, Node.js compatibility, storage requirements, and local Kubernetes setup. These improvements aim to make the setup experience smoother for future contributors.
Closes #1642