{"id":30113764,"url":"https://github.com/magicdude4eva/btc-fullnode-stack","last_synced_at":"2026-04-21T09:01:04.110Z","repository":{"id":305531489,"uuid":"1023133441","full_name":"magicdude4eva/btc-fullnode-stack","owner":"magicdude4eva","description":"Docker-based Bitcoin full node stack for Synology with Fulcrum, ckpool-solo, Mempool, and optional mining support.","archived":false,"fork":false,"pushed_at":"2026-04-10T07:07:45.000Z","size":114,"stargazers_count":11,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-10T09:03:49.180Z","etag":null,"topics":["bitcoin","bitcoin-node","bitcoind","ckpool","ckstats","docker","fulcrum","mempool","mining-dashboard","nerdqaxe","self-hosted","solo-mining","synology"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magicdude4eva.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["magicdude4eva"],"custom":["https://www.paypal.com/paypalme/GerdNaschenweng","https://accounts.binance.com/register?ref=13896895","https://www.kucoin.com/ucenter/signup?rcode=7wrbxe","https://crypto.com/app/ref6ayzqvp","https://dex.plutus.it/auth/referee/signup?refId=BUihTI"]}},"created_at":"2025-07-20T15:43:45.000Z","updated_at":"2026-03-31T20:09:18.000Z","dependencies_parsed_at":"2026-04-10T09:00:55.395Z","dependency_job_id":null,"html_url":"https://github.com/magicdude4eva/btc-fullnode-stack","commit_stats":null,"previous_names":["magicdude4eva/btc-fullnode-stack"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/magicdude4eva/btc-fullnode-stack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicdude4eva%2Fbtc-fullnode-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicdude4eva%2Fbtc-fullnode-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicdude4eva%2Fbtc-fullnode-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicdude4eva%2Fbtc-fullnode-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magicdude4eva","download_url":"https://codeload.github.com/magicdude4eva/btc-fullnode-stack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicdude4eva%2Fbtc-fullnode-stack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32084721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T06:27:27.065Z","status":"ssl_error","status_checked_at":"2026-04-21T06:27:21.250Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","bitcoin-node","bitcoind","ckpool","ckstats","docker","fulcrum","mempool","mining-dashboard","nerdqaxe","self-hosted","solo-mining","synology"],"created_at":"2025-08-10T07:29:08.311Z","updated_at":"2026-04-21T09:01:03.959Z","avatar_url":"https://github.com/magicdude4eva.png","language":"Shell","readme":"# ₿ Synology Bitcoin Node Stack\n![GitHub stars](https://img.shields.io/github/stars/magicdude4eva/btc-fullnode-stack?style=social)\n![GitHub forks](https://img.shields.io/github/forks/magicdude4eva/btc-fullnode-stack?style=social)\n![GitHub issues](https://img.shields.io/github/issues/magicdude4eva/btc-fullnode-stack)\n![GitHub last commit](https://img.shields.io/github/last-commit/magicdude4eva/btc-fullnode-stack)\n![GitHub repo size](https://img.shields.io/github/repo-size/magicdude4eva/btc-fullnode-stack)\n![Maintenance](https://img.shields.io/maintenance/yes/2025)\n[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://github.com/magicdude4eva/btc-fullnode-stack/issues)\n\nThis project sets up a **self-hosted Bitcoin infrastructure** on a **Synology NAS** (DS1019+ with 16GB RAM and 2TB NVME) using Docker. It is tailored for power users who want to:\n\n- Run a **fully validating Bitcoin full node**\n- Enable **solo mining** using their own ASIC hardware\n- Analyze mining statistics and mempool data\n- Operate with **full control**, **no third-party reliance**, and **local-first** architecture\n---\n\n## ⚙️ What's Included?\n\nThis stack brings together multiple containers to deliver a comprehensive, modular Bitcoin infrastructure:\n\n| Component             | Description |\n|----------------------|-------------|\n| **Bitcoin Core**     | The backbone: a full Bitcoin node that validates the entire blockchain and exposes RPC interfaces. |\n| **Fulcrum**          | High-performance Electrum server indexing the blockchain for wallet queries. |\n| **CKPool (Solo)**    | A modified solo mining pool implementation allowing ASIC miners to mine directly against your local node. |\n| **CKStats**          | Parses CKPool logs, stores mining events in PostgreSQL, and provides insights into hash rate, luck, and shares. |\n| **Bitcoin Explorer** | Web-based block explorer using RPC access to your Bitcoin Core. |\n| **Mempool**          | Powerful mempool visualizer and blockchain explorer (requires InfluxDB + Grafana). |\n| **InfluxDB**         | Time-series database used by Mempool and CKStats to store block and mempool metrics. |\n| **Grafana**          | Dashboards for visualizing metrics from InfluxDB (e.g., hash rate, block times, mempool size). |\n\n---\n\n## 💡 Why This Project?\n\nRunning your own Bitcoin full node is the most secure and private way to use Bitcoin. By adding:\n\n- **CKPool-solo**, you bypass centralized mining pools\n- **Fulcrum**, you serve your own wallets like Electrum\n- **Mempool + Explorer**, you get full insight into mempool congestion and fee estimation\n- **Self-hosted stack on Synology**, you stay in full control of your data and operations\n\nThis project automates the setup of a resilient, modular, and observable Bitcoin stack using Docker — optimized for **Synology NAS environments** but portable to any Linux system.\n\n---\n\n## 🔐 Self-Custody, Full Control, Maximum Privacy\n\nThis stack is designed around **sovereignty**:\n\n- No API keys  \n- No cloud services  \n- No third-party wallets  \n- No dependence on public electrum or explorer services  \n\nYou validate everything.  You own everything.  You mine for yourself.\n\n\n---\n\n## 🛠️ Installation \u0026 Setup\n\nTo get started, you only need a Synology NAS with Docker support (or any Linux machine) and around **700 GB of free disk space**. Performance varies depending on storage type.\n\n### 🧠 Storage Recommendations\n\nFor best results, especially during initial blockchain sync:\n\n- **Optimal Setup:** Place the full blockchain and indexes on a **fast NVMe volume** (≈700 GB total).\n- **Hybrid Setup (Recommended for Synology):**\n  - **Slow HDD** (e.g., `/volume1/data`) for blockchain data (`blocks` and `chainstate`)\n  - **Fast NVMe** (e.g., `/volume2/docker/appdata`) for:\n    - Bitcoin indexes (`indexes` folder, ~100 GB)\n    - All Docker configs and containers\n\n💡 On a Synology **DS1019+**, using this hybrid layout, the entire Bitcoin blockchain synced in just **4 days**.\n\n---\n\n### 🚀 Setup Steps\n\n1. **SSH into your Synology NAS** (or Linux host).\n\n2. **Download and execute the setup script**:\n\n   ```bash\n   curl -sSL https://raw.githubusercontent.com/magicdude4eva/btc-fullnode-stack/main/setup.sh | bash\n   ```\n\n3. **Follow the prompts**:\n   - Confirm or adjust the slow-storage path (`/volume1/data`) for blockchain data\n   - Confirm or adjust the fast-storage path (`/volume2/docker/appdata`) for configs, indexes, and container volumes\n\nThe setup script will:\n\n- ✅ Clone this repository into your fast NVMe volume\n- 🔐 Generate secure Bitcoin RPC credentials using `rpcauth.py`\n- 🔧 Automatically inject those credentials into:\n  - `bitcoin.conf` (for Bitcoin Core)\n  - `bitcoin-explorer.conf` (for BTC RPC Explorer)\n  - `ckpool.conf` (for the solo mining pool)\n- 📁 Prepare the required directory structure with proper ownership:\n  - UID/GID mapping for Docker containers\n  - Special user mappings for Postgres (CKStats), Grafana, and InfluxDB\n- 📊 Ensure fast index storage for optimal Bitcoin node performance\n\n## Starting\n\nTo get your full node up and running, follow these steps:\n\n### 1. Start the Bitcoin Node\n\nBegin by launching the Bitcoin Core node. This is the foundation for all other components.\n\n```bash\ndocker compose --profile bitcoin up -d bitcoind\n```\n\nYou can follow the logs to monitor its startup and sync status:\n```bash\ndocker logs -f bitcoin-node\n```\n### 2. Monitor Blockchain Sync Progress\n\nInitial synchronization can take **2–4 days**, depending on your system's NVMe/HDD speed and CPU performance.\n\nYou can check the progress using the following command:\n\n```bash\ndocker exec -it bitcoin-node bitcoin-cli -conf=/bitcoin/bitcoin.conf -datadir=/bitcoin getblockchaininfo\n```\nExample output: \n```json\n{\n  \"chain\": \"main\",\n  \"blocks\": 907250,\n  \"headers\": 907250,\n  \"bestblockhash\": \"000000000000000000017d6a511247219bdc9da8c5150eb3add0b41f99793613\",\n  \"bits\": \"1702349e\",\n  \"difficulty\": 127620086886391.8,\n  \"verificationprogress\": 0.9999998634713957,\n  \"initialblockdownload\": false,\n  \"size_on_disk\": 767801082543,\n  \"pruned\": false\n}\n```\n\nWatch for `\"initialblockdownload\": false` which means that the blockchain has fully synced and is ready. This means your node is fully synced and ready to serve RPC requests.\n\n\u003e ⚠️ **Important:** Do not start `cksolo` (the mining pool) or your miner before this status is reached. Mining during the initial download phase will lead to rejected shares and wasted energy.\n\n## CKSolo - Solo Mining Pool\n\n[CKSolo](https://bitbucket.org/ckolivas/ckpool-solo/src/solobtc/) is a lightweight, minimalist solo mining pool originally developed by Con Kolivas. It is ideal for miners who want to mine solo, directly submitting shares to their own Bitcoin Core node without relying on a third-party pool.\n\nIn this setup, **CKSolo** connects to your `bitcoind` node and handles incoming mining work submissions via the Stratum protocol. If your miner finds a valid block, it is directly submitted and credited to your Bitcoin address.\n\n\u003e 🛠 CKSolo logs all activity into `/volume2/docker/appdata/cksolo/logs/ckpool.log`, which is read by CKStats for statistics.\n\n### ⛏ Start CKSolo\n\nOnce `bitcoind` is fully synced, start CKSolo using:\n\n```bash\ndocker compose --profile bitcoin up -d ckpool\n```\n\nYou can monitor the log output with:\n```bash\ntail -f /volume2/docker/appdata/cksolo/logs/ckpool.log\n```\n\n## CKStats - CKSolo Stats Collector\n\n**CKStats** is a companion service for CKSolo. It continuously parses the CKSolo `ckpool.log` file and stores relevant mining metrics in an embedded PostgreSQL database. This enables historical tracking of:\n\n- Accepted and rejected shares\n- Miner activity and status\n- Found blocks (if you're lucky)\n- Hashrate trends\n\nCKStats is designed to be lightweight and runs alongside the solo pool to provide insights without adding unnecessary load or complexity.\n\n### 📊 Start CKStats\n\nOnce `ckpool` is running, start CKStats using:\n\n```bash\ndocker compose --profile bitcoin up -d ckstats\n```\n\nThis will spin up the `ckstats` service, connect it to the CKSolo-log file, and initialize the database under under `./ckstats/pgdata`\n\n\u003e ℹ️ The `pgdata` directory is owned by user `100` and group `103` to match PostgreSQL's internal user. Do not change these permissions.\n\n### ⚙️ Rebuilding or Reinitializing the Database\n\nCKStats supports two environment variables for maintenance and development purposes, which are set in the `docker-compose.yml`:\n```yaml\n  REBUILD_APP: \"0\"              # Set to \"1\" to rebuild the app and run the migration\n  DB_REINITIALISE: \"0\"          # Set to \"1\" to delete the entire database and wipe /ckstats/pgdata/*\n```\n\nSetting `REBUILD_APP=1` will trigger a fresh rebuild of the application and rerun any required database migrations during container startup.  \nThis is useful if you made changes to the CKStats codebase or updated dependencies and want to apply schema changes.\n\nSetting `DB_REINITIALISE=1` will **wipe all data** by deleting the entire PostgreSQL data directory (`/ckstats/pgdata/`) and initialize it from scratch.  \nUse this **with caution**, as all previously logged stats will be lost.\n\n🛑 **Important:**  \nThese flags only take effect during container startup. After a successful rebuild or reset, **you must set both values back to `0`** in your `docker-compose.yml` file to prevent unintended data loss on future restarts.\n\nCKStats automatically handles:\n- Full application rebuild (if requested)\n- Database schema migrations\n- Fresh initialization (if reset)\n\nOnce the CKStats container is running, you can access the stats dashboard via `http://\u003cyour-server-ip\u003e:4000`\n### Example Screenshots\n\u003cimg width=\"50%\" alt=\"image\" src=\"https://github.com/user-attachments/assets/570f1b54-2cdb-4958-acf5-f546ad249e43\" /\u003e\n\u003cimg width=\"50%\" alt=\"image\" src=\"https://github.com/user-attachments/assets/5fe3c2b4-d78f-4944-ac1d-ab8d00952d01\" /\u003e\n\nCKStats updates automatically and gives you complete visibility into the performance of your CKPool solo mining setup.\n\n## 📈 InfluxDB \u0026 Grafana\nThis dashboard is part of the self-hosted Bitcoin solo mining setup and provides a detailed overview of mining performance and hardware metrics in real-time. The **Grafana Mining Dashboard** connects to an InfluxDB time-series database and visualizes mining-related metrics such as:\n- ✅ Hashrate (1m, 5m, 1h, 1d, 7d)\n- 🧱 Shares (Accepted, Invalid, Duplicate)\n- 🔥 ASIC \u0026 VRM temperatures\n- ⚡ Power consumption (W), Voltage (V), Amperage (A)\n- ⏱️ Uptime (current session and total)\n- 🚫 Pool errors\n- 🎯 Best share difficulty\n\nThis setup is especially useful for monitoring performance and troubleshooting mining hardware or pool issues over time. Start both InfluxDB and Grafana services using the following command:\n\n```bash\ndocker compose --profile bitcoin up -d influxdb grafana\n```\nBoth services use credentials defined in your .env file. By default: Username: admin / Password: password\n\nOnce running, you can access the Grafana dashboard at: `http://\u003cyour-server-ip\u003e:3000`\n\u003cimg width=\"70%\" alt=\"image\" src=\"https://github.com/user-attachments/assets/886e664e-66b9-4144-9439-3c2db82c9e05\" /\u003e\n\n## 🛠️ Setting Up the NerdQAxe Miner\nOnce your backend services (Bitcoin node, CKSolo, InfluxDB, Grafana, and CKStats) are up and running, it’s time to connect your NerdQAxe miner.\n\n### 1. Configure Primary Stratum Pool\nHead to your NerdQAxe web UI and set the **Primary Stratum Pool** to connect to your local CKSolo instance:\n\n- **Stratum Host**: `192.168.1.97`  \n  *(replace with the IP of your Docker host)*\n- **Stratum Port**: `3333`\n- **Stratum User**: Your full mining address and worker name (e.g., `bc1...nerdqaxe01`)\n- **Stratum Password**: leave as is or set a placeholder like `x`\n\n\u003e ⚠️ Don't include `stratum+tcp://` or the port in the host field. The host should be a raw IP or hostname only.\n\u003cimg width=\"1738\" height=\"704\" alt=\"image\" src=\"https://github.com/user-attachments/assets/03335a6c-bac6-40d6-9b4d-4942729755e4\" /\u003e\n\n### 2. Configure InfluxDB Integration\nNext, enable InfluxDB metrics reporting so your miner stats appear in Grafana:\n\n- ✅ **Enable** the checkbox\n- **Influx URL**: `http://192.168.1.97` *(or your Docker host IP)*\n- **Influx Port**: `8086`\n- **Token**: from your `.env` file\n- **Bucket**: `nerdq_data` (defined in `.env`)\n- **Org**: `muffin_mining` (defined in `.env`)\n- **Prefix**: A unique identifier for the miner, e.g. `nerdq01`\n\nAfter saving, **reboot the miner** for changes to take effect.\n\u003cimg width=\"1382\" height=\"1010\" alt=\"image\" src=\"https://github.com/user-attachments/assets/d5db53c7-8fc0-4597-a5ed-5b52dc1d021f\" /\u003e\n\u003e 📌 Make sure the `Prefix` matches your naming in the Grafana dashboard to correctly group your stats.\n\n\n## ⚡ Fulcrum - Electrum Server for Fast Wallet Access\nFulcrum is a high-performance Electrum server written in C++, designed to serve light wallets with fast, index-based blockchain access. It's a critical component if you're running interfaces like **Mempool** or **Electrum wallets** and want **fast, efficient querying** of the Bitcoin blockchain without bogging down your full node.\n\n### 🧠 Why Do We Need Fulcrum?\n- **Index-based lookups**: Fulcrum allows wallet clients to quickly check balances, transactions, and history using indexed data.\n- **Mempool UI Backend**: The Mempool interface relies on Fulcrum to fetch live blockchain data and mempool information.\n- **Separation of Concerns**: Keeps your Bitcoin Core node lean while providing fast query capabilities to external tools.\n\n\u003e ❗ **Important:** Only start Fulcrum **after your Bitcoin node is fully synced**. Running Fulcrum during initial sync can lead to database corruption.\n\n### 🧊 Performance and Stability Warning\nEven with NVMe storage, **initialising Fulcrum takes time**. On a Synology DS1019+ with NVMe volumes, the initial index sync **took over a week**.\n- Do **not stop** Fulcrum or the NAS during this phase.\n- Any interruption can **corrupt the index** and require a full rebuild.\n- Consider disabling automatic reboots or DSM updates during initialisation.\n\n### ▶️ Starting Fulcrum\n```bash\ndocker compose --profile bitcoin --profile mempool up -d fulcrum\n```\n\nYou can monitor its logs with:\n```bash\ndocker logs -f mempool-fulcrum\n```\n\u003e ✅ Only proceed to set up Mempool or Electrum clients **after** Fulcrum has successfully completed its initial sync.\n\nAt that point, Fulcrum will be fully indexed and ready to serve queries. You should see log lines indicating it's listening for connections and serving indexes, e.g.:\n```\n[info] Now listening on 0.0.0.0:50001 (TCP) and 0.0.0.0:50002 (SSL)\n[info] Indexing complete. Ready to serve clients.\n```\n\n## Bitcoin Explorer\n[Bitcoin RPC Explorer](https://github.com/janoside/btc-rpc-explorer) is a web-based tool for inspecting and querying your local Bitcoin node. It provides an intuitive interface for viewing blocks, transactions, mempool activity, and various statistics pulled via RPC.\n\nThis is particularly useful when running your own full node, as it allows you to visualize what your node sees without needing to interact with raw RPC commands.\n\n### Prerequisites\nBefore starting Bitcoin Explorer, make sure that:\n- The **Bitcoin Node** is fully synced and running.\n- **Fulcrum** has completed its initial indexing (optional but recommended for completeness).\n\n### Starting the Explorer\n\nStart the container using:\n\n```bash\ndocker compose --profile bitcoin up -d bitcoin-explorer\n```\nThe explorer will attempt to connect to your Bitcoin node using the credentials from the `.env` file. If everything is set up correctly, you’ll be able to browse blocks, transactions, and node status in real time. Once running, the explorer is accessible via: `http://\u003cyour-server-ip\u003e:3002`:\n\u003cimg width=\"1370\" height=\"1130\" alt=\"image\" src=\"https://github.com/user-attachments/assets/be89c6bc-b817-420e-af77-18ce0a7fac05\" /\u003e\n\n\n\n\n## Donations are always welcome\n\n[paypal]: https://paypal.me/GerdNaschenweng\n\n🍻 **Support my work**  \nAll my software is free and built in my personal time. If it helps you or your business, please consider a small donation via [PayPal][paypal] — it keeps the coffee ☕ and ideas flowing!\n\n💸 **Crypto Donations**  \nYou can also send crypto to one of the addresses below:\n\n```\n(BTC)   bc1qdgdkk7l98pje8ny9u4xavsvrea8dw6yu8jpnyf\n(ETH)   0x5986f713A538D6bCaC0865564dCD45E2600A3469  \n(POL)   0x5986f713A538D6bCaC0865564dCD45E2600A3469\n(CRO)   0xb83c3Fe378F5224fAdD7a0f8a7dD33a6C96C422C (Cronos or Crypto.com Paystring magicdude$paystring.crypto.com)\n(BNB)   0x5986f713A538D6bCaC0865564dCD45E2600A3469\n(LTC)   ltc1qexst2exxksfyg7erfzlfrm23twkjgf7e5fn64t\n(DOGE)  DMQsxc9XGF6526drBJDZeX7AjFDJsEz4mN\n(SOL)   t4bYQCUuoCUrp7kJ4Mz314npcTuKoUSXj28UgdMrfTb\n```\n\n🧾 **Recommended Platforms**  \n- 👉 [Curve.com](https://www.curve.com/join#DWPXKG6E): Add your Crypto.com card to Apple Pay  \n- 🔐 [Crypto.com](https://crypto.com/app/ref6ayzqvp): Stake and get your free Crypto Visa card  \n- 📈 [Binance](https://accounts.binance.com/register?ref=13896895): Trade altcoins easily","funding_links":["https://github.com/sponsors/magicdude4eva","https://www.paypal.com/paypalme/GerdNaschenweng","https://accounts.binance.com/register?ref=13896895","https://www.kucoin.com/ucenter/signup?rcode=7wrbxe","https://crypto.com/app/ref6ayzqvp","https://dex.plutus.it/auth/referee/signup?refId=BUihTI","https://paypal.me/GerdNaschenweng"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicdude4eva%2Fbtc-fullnode-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagicdude4eva%2Fbtc-fullnode-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicdude4eva%2Fbtc-fullnode-stack/lists"}