hit-lacus commented on issue #16674: URL: https://github.com/apache/pinot/issues/16674#issuecomment-3269354163
Hi team and @ankitsultana , ### About ZK port I've successfully reproduced this issue. As pointed out, the root cause is a mismatch between the documentation and the default configuration files regarding the ZooKeeper port. The local setup documentation instructs users to start ZooKeeper on port 2191. However, the default configuration files (e.g., conf/pinot-controller.conf) expect ZooKeeper to be on port 2181. This inconsistency leads to the connection failure. I see two potential paths to resolve this for users: Option 1: Align with the configuration files. We can instruct users to start ZooKeeper on port 2181 to match the configuration. The command sequence would be: ```bash # Start ZK on port 2181 to match the default configs ./bin/pinot-admin.sh StartZookeeper -zkPort 2181 # Start other components as usual ./bin/pinot-admin.sh StartController -config conf/pinot-controller.conf ./bin/pinot-admin.sh StartBroker -config conf/pinot-broker.conf ./bin/pinot-admin.sh StartServer -config conf/pinot-server.conf ./bin/pinot-admin.sh StartMinion -config conf/pinot-minion.conf ``` Option 2 (Recommended): Align with the documentation. Alternatively, we can instruct users to modify their configuration files to use port 2191. This seems like a better long-term solution as it makes the config consistent with the documentation. Users would need to change `pinot.zk.server` from localhost:2181 to localhost:2191 in the relevant *.conf files before running the startup commands. I believe Option 2 is the better approach as it improves the out-of-the-box experience for anyone following the documentation. Perhaps we should consider updating the default configuration files in the source code to use 2191 permanently. -------- ### Some discussion I believe the root cause of the confusion in the "Running Pinot Locally" documentation is that it attempts to serve two different audiences with conflicting needs simultaneously: **General Users**: Their goal is to get a Pinot cluster running as quickly as possible. They need a simple, direct "happy path" with commands that work out-of-the-box. **Developers/Contributors**: Their goal is to set up a development environment. They need to understand the source code structure, build processes, and the location of source configuration templates (e.g., in src/main/resources). This dual-purpose approach leads to the exact problems we've seen: Conflicting Paths: The guide mentions the build/conf directory (for users) but also alludes to src/main/resources (for developers), causing confusion. Inconsistent Configurations: The recommended ZK port (2191) in the docs doesn't match the default configuration (2181), creating a roadblock for users, while the reason for this choice might be relevant context for developers. **Proposed Solution**: To provide a much clearer experience for everyone, I strongly suggest we split the current document into two distinct guides: **A "User Quick Start Guide"**: This guide would provide a single, verified path to get a local cluster running. It would use configurations that work perfectly together out-of-the-box. It would only reference the final build artifacts, with no mention of the source code structure. **A "Developer Onboarding Guide"**: This guide would cover building from source, setting up an IDE, and explaining the project structure. It would explain the purpose of `src/main/resources`, how configurations are templated, and provide context on development-specific practices. By separating these concerns, we can create a much smoother journey for both new users and future contributors. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
