docs: Enhance README with installation and configuration options - #99
docs: Enhance README with installation and configuration options#99RiH-137 wants to merge 1 commit into
Conversation
Added installation options for Polar, Docker, and manual Bitcoin Core setup. Updated prerequisites and configuration instructions for clarity. Comprehensive setup documentation: Lower Barriers to Entry - Multiple setup options (Polar/Docker/manual) accommodate different skill levels Faster Onboarding - Contributors can start in minutes vs hours Reproducible Environments - Consistent setups reduce debugging friction Ecosystem Growth - Easy local setup drives silent payment adoption Knowledge Sharing - Documentation becomes a learning resource Sustainable Maintenance - Self-service reduces maintainer burden
There was a problem hiding this comment.
Pull request overview
Enhances the project’s onboarding documentation by expanding the README’s installation/configuration guidance to support multiple local Bitcoin node setup paths (Polar, Docker, manual), aiming to reduce setup time and confusion for new contributors.
Changes:
- Expanded prerequisites to clarify recommended Node.js versions and Bitcoin node requirements.
- Added detailed configuration walkthroughs for Polar, Docker Compose, and manual Bitcoin Core setups.
- Added “Running the Application” verification steps and a troubleshooting section.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Visit `http://localhost/api` for API documentation | ||
| - Visit `http://localhost/silent-block/latest-height` to check indexed blocks |
There was a problem hiding this comment.
http://localhost/api does not appear to be served by the app (no Swagger setup / no controller mounted at /api). Consider changing this to an existing endpoint (e.g. /health) or documenting how to enable API docs if intended.
| - Visit `http://localhost/api` for API documentation | |
| - Visit `http://localhost/silent-block/latest-height` to check indexed blocks | |
| - Visit `http://localhost/silent-block/latest-height` to verify the indexer is responding and see the latest indexed block height |
| - In Polar: Use the "Mine Blocks" button | ||
| - With Docker: | ||
| ```bash | ||
| $ docker exec silent-pay-bitcoind bitcoin-cli -regtest -rpcuser=polaruser -rpcpassword=password generatetoaddress 10 <address> |
There was a problem hiding this comment.
The Docker mining example uses a fixed container name (silent-pay-bitcoind) and a placeholder written as <address>. Copy/pasting this will fail in most shells because <address> is treated as input redirection, and the container name may not match the actual container. Use a placeholder format that won’t be interpreted by the shell and document how to obtain an address (or include a complete example flow).
| $ docker exec silent-pay-bitcoind bitcoin-cli -regtest -rpcuser=polaruser -rpcpassword=password generatetoaddress 10 <address> | |
| # Replace YOUR_BITCOIND_CONTAINER_NAME with the actual container name (see `docker ps`) | |
| $ docker exec YOUR_BITCOIND_CONTAINER_NAME bitcoin-cli -regtest -rpcuser=polaruser -rpcpassword=password getnewaddress "mining" bech32 | |
| # Use the returned address in the following command (replace YOUR_REGTEST_ADDRESS) | |
| $ docker exec YOUR_BITCOIND_CONTAINER_NAME bitcoin-cli -regtest -rpcuser=polaruser -rpcpassword=password generatetoaddress 10 YOUR_REGTEST_ADDRESS |
| app: | ||
| port: 80 | ||
| verbose: false |
There was a problem hiding this comment.
The example config uses app.port: 80. On Linux/macOS, binding to ports <1024 typically requires elevated privileges, which can cause EACCES for local dev. Consider recommending a non-privileged default (e.g. 3000) or adding a note that users may need to change the port.
| - Visit `http://localhost/api` for API documentation | ||
| - Visit `http://localhost/silent-block/latest-height` to check indexed blocks |
There was a problem hiding this comment.
The verification URLs hardcode http://localhost/... without including the configured port. If users change app.port (as suggested later), these links will be incorrect; consider documenting them as http://localhost:<app.port>/... (or give both examples).
| - Visit `http://localhost/api` for API documentation | |
| - Visit `http://localhost/silent-block/latest-height` to check indexed blocks | |
| - Visit `http://localhost:<app.port>/api` (for example, `http://localhost:3000/api`) for API documentation | |
| - Visit `http://localhost:<app.port>/silent-block/latest-height` (for example, `http://localhost:3000/silent-block/latest-height`) to check indexed blocks |
| ```bash | ||
| $ docker compose -f "./e2e/helpers/docker/docker-compose.yml" up -d | ||
| ``` | ||
|
|
||
| This starts a Bitcoin Core regtest node with: | ||
| - RPC Port: `18443` | ||
| - RPC User: `polaruser` | ||
| - RPC Password: `password` | ||
|
|
There was a problem hiding this comment.
The Docker Compose command references ./e2e/helpers/docker/docker-compose.yml, but that file does not exist in the repository. Either add the compose file at that path, or update the README to point to the actual supported way to run a local bitcoind (currently the e2e setup uses Dockerode in e2e/setup.ts, not Compose).
Added installation options for Polar, Docker, and manual Bitcoin Core setup. Updated prerequisites and configuration instructions for clarity.
Comprehensive setup documentation:
Lower Barriers to Entry - Multiple setup options (Polar/Docker/manual) accommodate different skill levels Faster Onboarding - Contributors can start in minutes vs hours Reproducible Environments - Consistent setups reduce debugging friction Ecosystem Growth - Easy local setup drives silent payment adoption Knowledge Sharing - Documentation becomes a learning resource Sustainable Maintenance - Self-service reduces maintainer burden