docs: Add comprehensive setup guide and troubleshooting section #2092
Conversation
## Summary This PR significantly improves the developer experience for local Kleros v2 setup by adding missing configuration steps and comprehensive troubleshooting guidance. ## What's Added ### 🔧 Environment Setup Section - **API key requirements**: Step-by-step instructions for Alchemy and WalletConnect setup - **Environment file configuration**: Complete `.env.local` file creation with all required variables - **Alternative configuration methods**: Instructions for updating existing `.env.local.public` ### 🛠️ Comprehensive Troubleshooting Section - **8 common setup issues** with exact error messages and copy-paste solutions: 1. Volta yarn version errors (`volta pin yarn`) 2. Module resolution errors (kleros-app build dependency) 3. Environment variable errors (missing API keys) 4. Graph Node fulltext search errors (schema modification) 5. GraphQL code generation failures (endpoint testing) 6. Docker/Graph Node connection issues (port conflicts) 7. Web frontend loading issues (browser debugging) 8. Simulate task errors (working alternatives) ## Issues Addressed This PR addresses real-world problems that block new contributors: - **Missing environment variables** cause runtime errors with no clear guidance - **Volta configuration issues** prevent yarn commands from working - **Missing build dependencies** cause module resolution failures - **Broken simulation commands** (`simulate:all` task doesn't exist) - **No troubleshooting guidance** when things go wrong - **Port number discrepancies** between docs and actual behavior ## Testing These improvements are based on actual setup experience where each documented issue was encountered and resolved during a fresh repository clone and setup process. ## Impact This change will: - ✅ **Reduce onboarding friction** for new developers - ✅ **Save hours of debugging time** with ready solutions - ✅ **Improve developer experience** with clear, actionable guidance - ✅ **Prevent common setup failures** that discourage contributions ## Breaking Changes None. This is purely additive documentation that enhances the existing setup process without changing any functionality.
👷 Deploy request for kleros-v2-testnet pending review.Visit the deploys page to approve it
|
👷 Deploy request for kleros-v2-neo pending review.Visit the deploys page to approve it
|
👷 Deploy request for kleros-v2-testnet-devtools pending review.Visit the deploys page to approve it
|
👷 Deploy request for kleros-v2-university pending review.Visit the deploys page to approve it
|
WalkthroughDocumentation update to README.md adding environment setup guidance, explicit environment variables, standardized command formatting, expanded deployment steps, a detailed troubleshooting checklist, and links for getting help. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
Hi Kleros Team! 👋I just went through setting up Kleros v2 locally and hit several undocumented issues. This PR adds the missing setup steps and troubleshooting guidance that would have saved me (and future contributors) significant time. Key additions:
Every documented issue was actually encountered during fresh setup. Hope this helps make onboarding smoother for new contributors! |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🔭 Outside diff range comments (1)
README.md (1)
226-226: Update network name: Arbitrum Goerli → Arbitrum SepoliaElsewhere you reference ArbSepolia (REACT_APP_DRT_ARBSEPOLIA_SUBGRAPH). Goerli is deprecated; this label should reflect Sepolia to avoid confusion.
-##### Based on the ArbitrumGoerli deployment artifacts +##### Based on the Arbitrum Sepolia deployment artifacts
🧹 Nitpick comments (5)
README.md (5)
65-77: Convert emphasized labels to actual subheadings for consistency and to satisfy MD036Use proper Markdown headings instead of bold text used as headings. This improves navigability and fixes the markdownlint warning.
Apply this diff:
-### Environment Setup +### Environment setup @@ -**API Keys (Required):** +#### API keys (required) @@ -**Environment Configuration** +#### Environment configuration
79-90: Add language to code fence and include a non-commit warning for secrets
- Specify a language for fenced blocks (markdownlint MD040).
- Explicitly warn not to commit .env.local, since it will contain secrets.
- - Create a `.env.local` file in `/web` (or update an existing `.env.local.public`): +- Create a `.env.local` file in `/web` (or update an existing `.env.local.public`): + +> Do not commit `.env.local`; it contains secrets. @@ - ``` + ```bash cd web cat > .env.local << EOF REACT_APP_CORE_SUBGRAPH=http://localhost:8000/subgraphs/name/kleros/kleros-v2-core-local REACT_APP_DRT_ARBSEPOLIA_SUBGRAPH=http://localhost:8000/subgraphs/name/kleros/kleros-v2-drt-local ALCHEMY_API_KEY=your_alchemy_api_key_here WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id_here EOF @@ -``` +```
241-243: Add code fence languages to satisfy MD040 and improve readabilitySeveral fenced blocks are missing language specifiers. Add bash for shell snippets.
- ``` + ```bash volta pin yarn ```- ``` + ```bash yarn workspace @kleros/kleros-app build ```- ``` + ```bash cd subgraph/core # Remove @fulltext directives from schema.graphql sed -i '/@fulltext(/,/)/d' schema.graphql rm -rf build/ yarn build```diff - ``` + ```bash curl -X POST -H "Content-Type: application/json" \ -d '{"query": "{ _meta { block { number } } }"}' \ http://localhost:8000/subgraphs/name/kleros/kleros-v2-core-local```diff - ``` + ```bash docker system prune -fAlso applies to: 248-250, 261-267, 275-279, 287-289 --- `258-267`: **Clarify scope of schema edits and advise on reverting changes** Removing @fulltext directives is a local workaround. Add a note that these changes should not be committed and how to revert them, to prevent accidental drift. ```diff # Remove @fulltext directives from schema.graphql sed -i '/@fulltext(/,/)/d' schema.graphql rm -rf build/ yarn build + # Note: Do not commit these local schema changes. Revert with: + # git restore subgraph/core/schema.graphql
281-289: Use targeted cleanup before resorting to docker system prune
docker system prune -fis destructive. Prefer targeted cleanup first; reserve prune for last resort.- docker system prune -f + # Prefer targeted cleanup: + yarn workspace @kleros/kleros-v2-subgraph stop-local-indexer + # Or, from the subgraph package directory: + # docker compose down -v + # As a last resort: + # docker system prune -f
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
README.md(7 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[grammar] ~69-~69: There might be a mistake here.
Context: ... API Key** (for blockchain connectivity) - Sign up at [alchemy.com](https://www.alc...
(QB_NEW_EN)
[grammar] ~73-~73: There might be a mistake here.
Context: ...ct Project ID** (for wallet connections) - Sign up at [cloud.walletconnect.com](htt...
(QB_NEW_EN)
[grammar] ~238-~238: There might be a mistake here.
Context: ...Solutions - Volta Yarn Version Errors - Pin yarn version in the project root. ...
(QB_NEW_EN)
[grammar] ~245-~245: There might be a mistake here.
Context: ...rn ``` - Module Resolution Errors - Build the kleros-app package first. ...
(QB_NEW_EN)
[grammar] ~252-~252: There might be a mistake here.
Context: ... ``` - Environment Variable Errors - Ensure all required variables are presen...
(QB_NEW_EN)
[grammar] ~258-~258: There might be a mistake here.
Context: ... - **Graph Node Fulltext Search Errors** - Remove@fulltext` directives from the s...
(QB_NEW_EN)
[grammar] ~296-~296: There might be a mistake here.
Context: ...ost:8000/). - Simulate Task Not Found - Run tests: `yarn workspace @kleros/klero...
(QB_NEW_EN)
[grammar] ~297-~297: There might be a mistake here.
Context: ...imulate Task Not Found** - Run tests: yarn workspace @kleros/kleros-v2-contracts test - Use dispute bot: `yarn workspace @kleros...
(QB_NEW_EN)
[grammar] ~298-~298: There might be a mistake here.
Context: ...v2-contracts test - Use dispute bot:yarn workspace @kleros/kleros-v2-contracts bot:disputor` - Or simulate disputes via the web interfa...
(QB_NEW_EN)
🪛 markdownlint-cli2 (0.17.2)
README.md
77-77: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
81-81: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
94-94: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
241-241: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
248-248: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
261-261: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
275-275: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
287-287: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
README.md (2)
65-109: Great doc expansion: setup, env, deployment, and troubleshooting are much clearerThis is a substantial improvement in onboarding, with actionable steps and copy-paste commands. The troubleshooting matrix is especially helpful.
Also applies to: 123-193, 194-234, 236-309
245-251: Workspace name confirmed: @kleros/kleros-app
The script listed all workspaces and showed thatkleros-app/package.jsondefines the package as@kleros/kleros-app. The README instruction is correct—no change needed.
Summary
This PR significantly improves the developer experience for local Kleros v2 setup by adding missing configuration steps and comprehensive troubleshooting guidance.
What's Added
Environment Setup Section
.env.localfile creation with all required variables.env.local.publicComprehensive Troubleshooting Section
volta pin yarn)Issues Addressed
This PR addresses real-world problems that block new contributors:
simulate:alltask doesn't exist)Testing
These improvements are based on actual setup experience where each documented issue was encountered and resolved during a fresh repository clone and setup process.
Impact
This change will:
Breaking Changes
None. This is purely additive documentation that enhances the existing setup process without changing any functionality.
PR-Codex overview
This PR focuses on enhancing the
README.mdby adding detailed environment setup instructions, troubleshooting tips, and clarifying the configuration process for API keys and local development.Detailed summary
.env.localand.env.local.public.yarncommands for consistency.Summary by CodeRabbit