|
| 1 | +[](#) |
| 2 | +[](https://bitcoincore.org/en/releases/) |
| 3 | +[](https://github.com/romanz/electrs?tab=readme-ov-file#readme) |
| 4 | + |
| 5 | +# Bitcoin Mac Node Builder |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +Automated, configurable installer and dashboard for running a self-hosted [Bitcoin Core full node](https://github.com/bitcoin/bitcoin) and optional [Electrs](https://github.com/romanz/electrs) (Electrum server) on macOS. Running a full node with Electrs allows you to directly connect popular wallets, including [Electrum](https://electrum.org) and [Sparrow Wallet](https://www.sparrowwallet.com). This give you the privacy and financial self-sovereignty to check wallet balances and send transactions without trusting third party servers. |
| 12 | + |
| 13 | +Bitcoin Mac Node builder supports: |
| 14 | +* Building Bitcoin Core and Electrs from GitHub source (or by downloading verified binaries) |
| 15 | +* Concise installer progress updates with detailed popup views and logging for troubleshooting |
| 16 | +* Multiple Bitcoin Core versions (29.x, 30.x, master branch) with fast version switching |
| 17 | +* Generating Bitcoin Core and Electrs config files (`bitcoin.conf`, `config.toml`) from simple, well-documented meta settings file ([global_config.yaml](./global_config.yaml)) |
| 18 | +* Real-time monitoring with the included terminal node monitor dashboard (`node-monitor.sh`) |
| 19 | + |
| 20 | +For maintainability and transparency, all the scripts are written in zsh (the default shell on macOS). |
| 21 | + |
| 22 | +## Built for macOS |
| 23 | +While other Bitcoin Core node builders exist, Bitcoin Mac Node Builder is specifically designed to make installation and configuration of Bitcoin Core and Electrs on macOS both robust and easy-to-maintain: |
| 24 | + |
| 25 | +- Complete installation and configuration process from A to Z: |
| 26 | + - Downloading from GitHub (using tag or branch identifer to specify version) |
| 27 | + - Installation of all dependencies |
| 28 | + - Installation and configuration of Tor (optional) |
| 29 | + - Building from source (or optional use of verified binary downloads) |
| 30 | + - Running unit tests (optional) |
| 31 | + - Generation of config files |
| 32 | + - Generation and installation of macOS launch agents |
| 33 | + - Terminal node monitor dashboard with adaptive layout of status and logs |
| 34 | +- Installed macOS launch agents and launch helper scripts: |
| 35 | + - Start Bitcoin Core and Electrs daemons on macOS user login |
| 36 | + - Start daemons when target SSD volumes mount (useful for MacBooks with external SSDs) |
| 37 | + - Delay Electrs startup until after Bitcoin Core is running |
| 38 | + - Automatically relaunch daemons after any unexpected shutdowns |
| 39 | + |
| 40 | +Once the Bitcoin initial block download has completed, your macOS node will run quietly in the background using negligable CPU resources. Running a MacBook that isn't always connected to your node's external SSD? Bitcoin Mac Node Builder will automatically detect the external SSD when it is connected and quickly catch-up your node to the lastest block. |
| 41 | + |
| 42 | +### Simplified Configuration |
| 43 | +Configuring Bitcoin Core's `bitcoin.conf` file can be a complex process. Its configuration options have evolved over more than a decade and the interactions between some options can be unintuitive. Bitcoin Mac Node Builder automates the process by generating the config files (Bitcoin Core's `bitcoin.conf` and Electrs's `config.toml`) from a simpler, well-documented meta settings file: [global_config.yaml](./global_config.yaml). This simplified settings file provides the configuration options most often needed for a self-hosted Bitcoin node, while also allowing for raw config options to be passed through during config file generation. |
| 44 | + |
| 45 | +### Seamless Tor and Electrs Integration |
| 46 | +The simplified [global_config.yaml](./global_config.yaml) meta settings file is also used to automatically configure Tor for privacy (if enabled) and ensure Electrs compatibility. No more guessing how to configure Bitcoin and Electrs to work together – just enable Electrs in the meta settings file and Bitcoin Mac Node Builder will do the rest. |
| 47 | + |
| 48 | +## Requirements |
| 49 | + |
| 50 | +- macOS with Xcode Command Line Tools (auto-installed if missing) |
| 51 | +- Sufficient storage (blockchain + indexes can be large; 1 TB recommended) |
| 52 | +- External SSD strongly recommended for performance |
| 53 | + |
| 54 | +## Installing and Usage |
| 55 | + |
| 56 | +1. Quit the Bitcoin GUI app or stop the `bitcoind` daemon if either is running. |
| 57 | +2. Git clone the repo and edit `global_config.yaml` to specify your install destination paths (`target_path`). |
| 58 | + ```zsh |
| 59 | + git clone https://github.com/pricklypierre/bitcoin-mac-node-builder |
| 60 | + cd bitcoin-mac-node-builder |
| 61 | + open global_config.yaml |
| 62 | + ``` |
| 63 | + |
| 64 | +  |
| 65 | +  |
| 66 | + The blockchain and indexes need slightly less than 1 TB of storage, so an external SSD is recommended. You can make other configuration changes in `global_config.yaml`, but the defaults are configured to work well for most users and the installer scripts can be re-run if changes are later needed. |
| 67 | +3. Execute the Bitcoin Core installer script: |
| 68 | + ```zsh |
| 69 | + ./bitcoin-core-install.sh |
| 70 | + ``` |
| 71 | + If Xcode Command Line Tools are missing, the installer will prompt you to install them and re-run the installer script. When the Bitcoin Core daemon starts, macOS may prompt to allow access to the external drive and you will be notified of the `start-bitcoind` background item being added. |
| 72 | + |
| 73 | +  |
| 74 | +4. Optionally execute the Electrs Electrum Server installer script: |
| 75 | + ```zsh |
| 76 | + ./electrs-install.sh |
| 77 | + ``` |
| 78 | + When the Electrs daemon starts, macOS will show similar notifications as with Bitcoin Core. |
| 79 | +5. The initial block download (IBD) can take a long time (possibly days), depending on your ISP speed and SSD performance. Note the Electrs daemon will wait until after the IBD is complete to start its indexing (which takes several hours). To monitor both services start the node monitor dashboard: |
| 80 | + ```zsh |
| 81 | + ./node-monitor.sh |
| 82 | + ``` |
| 83 | + The node monitor has an adaptive layout, so resizing the Terminal window will show more information, including live logs for troubleshooting: |
| 84 | +  |
| 85 | + The daemons are started automatically by the installers. For manually stopping/starting the daemons from the dashboard press:<br> `B` (Bitcoin) `E` (Electrs) `Q` (quit the dashboard) |
| 86 | + |
| 87 | +## Connecting Electrum Wallet to Electrs |
| 88 | + |
| 89 | +After Bitcoin Core + Electrs are installed and the initial block download (and Electrs indexing) is complete, you can connect your [Electrum Wallet](https://electrum.org) directly to your node. |
| 90 | + |
| 91 | +1. Use the node monitor dashboard (`node-monitor.sh`) to monitor Bitcoin Core and Electrs. Wait for Bitcoin Core to complete the initial block download, and wait for Electrs to finish indexing. |
| 92 | +2. Quit the Electrum Wallet app if it is running, or use `electrum stop` from the Terminal if the daemon is running. |
| 93 | +3. Modify the Electrum Wallet configuration so that it only connects to your local Electrs server: |
| 94 | + ```zsh |
| 95 | + ELECTRS_IP="127.0.0.1" |
| 96 | + electrum daemon &; sleep 3 |
| 97 | + electrum setconfig auto_connect false |
| 98 | + electrum setconfig oneserver true |
| 99 | + electrum setconfig server ${ELECTRS_IP}:50001:t |
| 100 | + electrum stop |
| 101 | + ``` |
| 102 | + If your Electrum wallet is on a different Mac than your node, then change change `ELECTRS_IP="127.0.0.1"` to your local Electrs server IP address. |
| 103 | +4. Relaunch the Electrum Wallet app. |
| 104 | +5. Verify that Electrum is connected to your local Electrs server via: |
| 105 | + ```zsh |
| 106 | + electrum getinfo | jq -r '.connected, .spv_nodes, .server' |
| 107 | + ``` |
| 108 | + which should return something like this: |
| 109 | + ``` |
| 110 | + true |
| 111 | + 1 |
| 112 | + 127.0.0.1 |
| 113 | + ``` |
| 114 | + indicating that it is connected (`true`) to one server (`1`) that matches the local Electrs server IP address (`127.0.0.1`) you specified by `ELECTRS_IP`. |
| 115 | +6. Bask in the joy of financial self-sovereignty. |
| 116 | + |
| 117 | +## Connecting Sparrow Wallet to Electrs |
| 118 | + |
| 119 | +You can also connect your [Sparrow Wallet](https://www.sparrowwallet.com) directly to your node. By using Bitcoin Core + Electrs, you can enable "[Expert Stage](https://sparrowwallet.com/docs/best-practices.html#the-expert-stage)" mode in Sparrow, which allows you to directly use Electrs when managing wallets and sending transactions. |
| 120 | + |
| 121 | +1. Use the node monitor dashboard (`node-monitor.sh`) to monitor Bitcoin Core and Electrs. Wait for Bitcoin Core to complete the initial block download, and wait for Electrs to finish indexing. |
| 122 | +2. Choose the `Sparrow->Setting` menu and under the `Server` panel choose the `Private Electrum` type option: |
| 123 | + |
| 124 | +  |
| 125 | +3. Use the settings: |
| 126 | + |
| 127 | +  |
| 128 | + - URL: `127.0.0.1` or your local Electrs server IP address |
| 129 | + - Port: `50001` |
| 130 | + - Use SSL: `Off / Disabled` |
| 131 | +4. Press the `Test Connection` button. |
| 132 | + |
| 133 | +  |
| 134 | +5. Bask in the joy of financial self-sovereignty. |
| 135 | + |
| 136 | +## Using with an Existing Bitcoin Core Installation |
| 137 | + |
| 138 | +Although the Bitcoin Mac Node Builder is designed to install and configure Bitcoin Core from scratch, it can also be used with an existing Bitcoin Core installation to avoid having to re-download and verify all the blocks. Note that the `bitcoin-core-install.sh` script creates an an alias (symlink) here: |
| 139 | + |
| 140 | + `~(user folder)/Library/Application Support/Bitcoin` |
| 141 | + |
| 142 | +to the Bitcoin Core `target_path` specified in the `global_config.yaml` so that Bitcoin Core commands find the config file and data directories. If you have a previous Bitcoin Core installation that has installed directly to that default location, then `bitcoin-core-install.sh` will fail to install since it cannot safely create the symlink. |
| 143 | + |
| 144 | +If you have a previous Bitcoin Core installation then: |
| 145 | + |
| 146 | +1. Rename or move the folder (if it exists): |
| 147 | + |
| 148 | + `~(user folder)/Library/Application Support/Bitcoin` |
| 149 | +2. Execute the Bitcoin Core installer script (see detailed steps above): |
| 150 | + ```zsh |
| 151 | + cd bitcoin-mac-node-builder |
| 152 | + ./bitcoin-core-install.sh |
| 153 | + ``` |
| 154 | +3. Execute the installed `stop.sh` script to stop the Bitcoin Core daemon. |
| 155 | +4. Copy from the previous installation into the new installation (specified by `target_path` in the `global_config.yaml`) the following directories and files: |
| 156 | + - `blocks/` |
| 157 | + - `chainstate/` |
| 158 | + - `indexes/` |
| 159 | + - `anchors.dat` |
| 160 | + - `peers.dat` |
| 161 | + - `banlist.json` |
| 162 | +5. Bitcoin Mac Node Builder automatically generates the `bitcoin.conf` to ensure Electrs (and optionally Tor) compatibility, so it is recommended to use it if possible. If you have a custom `bitcoin.conf` file then you can copy it into the new installation, but note you will need to set `generate_config_file` to `false` in the `global_config.yaml` file, so subsequent runs of the installer will not overwrite your custom `bitcoin.conf` file. |
| 163 | +6. Execute the installed `start.sh` script to re-start the Bitcoin Core daemon. |
| 164 | +7. Monitor the Bitcoin Core startup using the node monitor dashboard: |
| 165 | + ```zsh |
| 166 | + cd bitcoin-mac-node-builder |
| 167 | + ./node-monitor.sh |
| 168 | + ``` |
| 169 | + |
| 170 | +## Installer Script Options |
| 171 | + |
| 172 | +Options for `bitcoin-core-install.sh`: |
| 173 | +``` |
| 174 | +-c Clean install. Forces fresh download and complete rebuild. |
| 175 | +-f Fast install only source and config changes. Skips dependency and startup checks. |
| 176 | + A complete build must be done initially to install dependencies. |
| 177 | +-u Uninstall Bitcoin Core but leaves data directories: blocks, chainstate, indexes. |
| 178 | +-uu Uninstall Bitcoin Core including all data directories. |
| 179 | +``` |
| 180 | + |
| 181 | +Options for `electrs-install.sh`: |
| 182 | +``` |
| 183 | +-c Clean install. Forces fresh download and complete rebuild. |
| 184 | +-f Fast install only source and config changes. Skips dependency and startup checks. |
| 185 | + A complete build must be done initially to install dependencies. |
| 186 | +-u Uninstall Electrs Electrum Server but leaves 'db' data directory. |
| 187 | +-uu Uninstall Electrs Electrum Server including all data directories. |
| 188 | +``` |
| 189 | + |
| 190 | +## License |
| 191 | + |
| 192 | +MIT License. See LICENSE.txt for details. |
0 commit comments