Add Docker setup for BitcoinPurple explorer

- Dockerfile: node:20-alpine, compiles SCSS at build time, single image used for web server and all sync modes (blocks, peers, markets) - docker-compose.yml: explorer + MongoDB (bind-mounted ./db) on shared 'purple' network alongside bitcoinpurpled and electrumx - docker/entrypoint.sh: generates settings.json from env vars via envsubst, dispatches to web/sync-blocks/sync-peers/reindex modes - docker/settings.json.tmpl: minimal settings template parametrized for BitcoinPurple (coin, wallet RPC, MongoDB, theme) - docker/mongo-init.sh: creates app user in explorerdb on first start - .env.example: pre-filled defaults for BitcoinPurple - CLAUDE.md: codebase guidance for Claude Code - .gitignore: add db/ (MongoDB bind-mount data directory)
2026-04-28 13:39:45 +02:00
parent 057c592a21
commit 306f494cd8
9 changed files with 560 additions and 1 deletions
@@ -0,0 +1,12 @@
+node_modules/
+db/
+tmp/
+.git/
+.gitignore
+settings.json
+*.log
+explorerdb_dump.7z
+docker-compose.yml
+.env
+.env.*
+!.env.example
@@ -0,0 +1,30 @@
+# ─── Coin ────────────────────────────────────────────────────────────────────
+COIN_NAME=BitcoinPurple
+COIN_SYMBOL=BTCP
+# POW, POS, or Hybrid
+COIN_DIFFICULTY=POW
+
+# ─── MongoDB (internal to this stack) ────────────────────────────────────────
+MONGO_HOST=mongodb
+MONGO_PORT=27017
+MONGO_USER=eiquidus
+MONGO_PASSWORD=change-me
+MONGO_DATABASE=explorerdb
+
+# ─── Wallet RPC ───────────────────────────────────────────────────────────────
+# bitcoinpurpled container is reachable on the shared 'purple' Docker network
+WALLET_RPC_HOST=bitcoinpurpled
+WALLET_RPC_PORT=13495
+# Copy rpcuser / rpcpassword values from ~/.bitcoinpurple/bitcoinpurple.conf
+WALLET_RPC_USER=
+WALLET_RPC_PASS=
+
+# ─── Explorer web ────────────────────────────────────────────────────────────
+# Host port the explorer is published on
+EXPLORER_PORT=3001
+# Bootswatch theme: Cerulean, Cosmo, Cyborg, Darkly, Flatly, Slate, Solar, ...
+EXPLORER_THEME=Darkly
+
+# ─── Sync intervals (seconds) ────────────────────────────────────────────────
+SYNC_BLOCKS_INTERVAL=120
+SYNC_PEERS_INTERVAL=300
@@ -10,6 +10,7 @@ logs
 pids
 *.pid
 *.seed
+db/

 # Directory for instrumented libs generated by jscoverage/JSCover
 lib-cov
@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**eIquidus** — a Node.js/Express blockchain block explorer for altcoins using the Bitcoin RPC protocol. It connects to a coin wallet via JSON-RPC, syncs blocks/transactions into MongoDB, and serves a web UI.
+
+- Node.js ≥ 20.9.0, MongoDB ≥ 7.0.2
+- Express v5, Pug templates, Mongoose ODM, Jasmine tests
+- Configuration lives entirely in `settings.json` (created from `settings.json.template`)
+
+## Common Commands
+
+```bash
+# Run tests
+npm test                   # jasmine test/*Spec.js
+
+# Start the explorer
+npm start                  # cluster mode (1 worker per CPU)
+npm run start-instance     # single instance (dev/testing)
+npm run start-pm2          # production via PM2
+
+# Blockchain sync (run as separate processes, not part of the web server)
+npm run sync-blocks        # sync new blocks from wallet
+npm run sync-markets       # fetch exchange market data
+npm run sync-peers         # discover network peers
+npm run sync-masternodes   # update masternode list
+npm run check-blocks       # verify block integrity
+
+# Database maintenance
+npm run reindex            # full reindex from wallet RPC
+npm run create-backup      # backup MongoDB
+npm run restore-backup     # restore MongoDB
+npm run delete-database    # wipe all explorer data
+
+# CSS compilation (SASS → CSS in public/css/)
+node scripts/compile_css.js
+```
+
+## Architecture
+
+### Request Flow
+
+```
+HTTP request
+  → app.js (middleware: CORS, rate limiting, auth, TLS redirect)
+  → routes/index.js (all web & API routes)
+  → lib/database.js (Mongoose queries against models/)
+  → lib/explorer.js (data transformation utilities)
+  → views/*.pug (rendered response)
+```
+
+For live wallet data, routes call `lib/nodeapi.js` which wraps `lib/jsonrpc.js` for RPC calls.
+
+### Sync Flow
+
+```
+npm run sync-blocks
+  → scripts/sync.js (orchestrator, uses worker threads)
+  → lib/block_sync.js (parallel block fetching & processing)
+  → lib/database.js (bulk writes to MongoDB)
+```
+
+Block sync is multi-threaded (configurable parallelism). It has elastic stack-size handling for overflow errors. **The web server and sync scripts are separate processes** — sync is triggered via cron, not by the web server.
+
+### Key Files
+
+| File | Purpose |
+|---|---|
+| `app.js` | Express setup: plugin loader, CORS, ACL builder, TLS redirect |
+| `lib/settings.js` | Parses and validates `settings.json`; all config access goes through here |
+| `lib/database.js` | All MongoDB queries; wraps Mongoose models |
+| `lib/explorer.js` | Pure utility functions for formatting block/tx/address data |
+| `lib/block_sync.js` | Multi-threaded block synchronization engine |
+| `lib/nodeapi.js` | Wallet RPC wrapper |
+| `routes/index.js` | All Express routes (web pages + REST API) |
+| `scripts/sync.js` | Entry point for `npm run sync-*` commands |
+| `models/` | 12 Mongoose schemas: `tx`, `address`, `addresstx`, `stats`, `richlist`, `masternode`, `peers`, `markets`, `orphans`, `heavy`, `networkhistory`, `claimaddress` |
+| `lib/markets/` | Per-exchange integrations (altmarkets, dextrade, dexomy, freiexchange, nonkyc, poloniex, xeggex, yobit) |
+
+### Configuration
+
+`settings.json` (gitignored, based on `settings.json.template`) controls everything: DB credentials, wallet RPC, port, TLS, themes, enabled pages, market exchanges, API access. Read through `lib/settings.js` to understand available options and their defaults.
+
+### Plugin System
+
+Early-stage plugin system. Plugins are loaded in `app.js` from the `plugins/` directory. Currently a placeholder only.
+
+### Testing
+
+Tests are in `test/` using Jasmine:
+- `explorerSpec.js` — tests for `lib/explorer.js` utilities
+- `marketSpec.js` — tests for market helper functions
+- `testData.js` — shared fixtures
+
+There is no linting configured. No TypeScript.
@@ -0,0 +1,21 @@
+FROM node:20-alpine
+
+# gettext provides envsubst for settings.json template rendering
+RUN apk add --no-cache gettext bash
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install --omit=dev
+
+COPY . .
+
+# Compile SCSS → CSS (prestart.js also connects to MongoDB which isn't available at build time)
+RUN node ./scripts/compile_css.js
+
+RUN chmod +x /app/docker/entrypoint.sh && mkdir -p /app/tmp
+
+EXPOSE 3001
+
+ENTRYPOINT ["/app/docker/entrypoint.sh"]
+CMD ["web"]
@@ -0,0 +1,102 @@
+networks:
+  purple:
+    external: true   # shared with purple-stack (bitcoinpurpled, electrumx)
+  explorer-internal: # isolates MongoDB from the outside world
+    name: purple-explorer-internal
+
+services:
+  mongodb:
+    image: mongo:7
+    container_name: purple-explorer-mongodb
+    restart: unless-stopped
+    networks:
+      - explorer-internal
+    volumes:
+      # Keep MongoDB data in this repository's ./db directory.
+      # Do not switch this back to a named Docker volume or the explorer will
+      # stop using the already-synced local database.
+      - type: bind
+        source: ./db
+        target: /data/db
+        bind:
+          create_host_path: true
+      - ./docker/mongo-init.sh:/docker-entrypoint-initdb.d/init.sh:ro
+    environment:
+      # Root admin (used only by the init script to bootstrap the app user)
+      MONGO_INITDB_ROOT_USERNAME: mongoadmin
+      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
+      # Passed into mongo-init.sh to create the explorer app user
+      MONGO_APP_USER: ${MONGO_USER}
+      MONGO_APP_PASS: ${MONGO_PASSWORD}
+      MONGO_APP_DB: ${MONGO_DATABASE:-explorerdb}
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  explorer:
+    build: .
+    image: purple-explorer:local
+    container_name: purple-explorer
+    restart: unless-stopped
+    depends_on:
+      - mongodb
+    networks:
+      - purple           # reach bitcoinpurpled:13495 for RPC
+      - explorer-internal
+    ports:
+      - "0.0.0.0:${EXPLORER_PORT:-3001}:3001"
+    env_file: .env
+    command: web
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  sync-blocks:
+    image: purple-explorer:local
+    container_name: purple-explorer-sync-blocks
+    restart: unless-stopped
+    depends_on:
+      - mongodb
+      - explorer   # ensures the image is built before this runs
+    networks:
+      - purple           # reach bitcoinpurpled RPC
+      - explorer-internal
+    env_file: .env
+    command: sync-blocks
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  # sync-markets: disabled until exchanges are configured in docker/settings.json.tmpl
+  # To enable: uncomment, configure markets_page.exchanges in the template, then redeploy.
+  # sync-markets:
+  #   image: purple-explorer:local
+  #   container_name: purple-explorer-sync-markets
+  #   restart: unless-stopped
+  #   depends_on: [mongodb]
+  #   networks: [explorer-internal]
+  #   env_file: .env
+  #   command: sync-markets
+
+  sync-peers:
+    image: purple-explorer:local
+    container_name: purple-explorer-sync-peers
+    restart: unless-stopped
+    depends_on:
+      - mongodb
+    networks:
+      - purple           # reach bitcoinpurpled for peer info
+      - explorer-internal
+    env_file: .env
+    command: sync-peers
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
@@ -0,0 +1,58 @@
+#!/bin/sh
+set -e
+
+# Generate settings.json from template using environment variables
+envsubst < /app/docker/settings.json.tmpl > /app/settings.json
+
+MODE="${1:-web}"
+
+case "$MODE" in
+  web)
+    # Initialize DB collections/stats document before starting workers
+    # (equivalent to what prestart.js does before launching pm2/forever)
+    node -e "
+      const db = require('./lib/database');
+      db.connect(null, function() {
+        db.initialize_data_startup(function() {
+          process.exit(0);
+        });
+      });
+    "
+    exec node --stack-size=10000 ./bin/cluster
+    ;;
+
+  sync-blocks)
+    echo "[sync-blocks] Starting block sync loop (interval: ${SYNC_BLOCKS_INTERVAL:-120}s)"
+    while true; do
+      node --stack-size=10000 ./scripts/sync.js index update || true
+      sleep "${SYNC_BLOCKS_INTERVAL:-120}"
+    done
+    ;;
+
+  sync-markets)
+    echo "[sync-markets] Starting market sync (runs in internal loop)"
+    exec node --stack-size=10000 ./scripts/sync.js market
+    ;;
+
+  sync-peers)
+    echo "[sync-peers] Starting peer sync loop (interval: ${SYNC_PEERS_INTERVAL:-300}s)"
+    while true; do
+      node --stack-size=10000 ./scripts/sync.js peers || true
+      sleep "${SYNC_PEERS_INTERVAL:-300}"
+    done
+    ;;
+
+  reindex)
+    echo "[reindex] Running full reindex..."
+    exec node --stack-size=10000 ./scripts/sync.js index reindex
+    ;;
+
+  check-blocks)
+    echo "[check-blocks] Checking for missing transactions..."
+    exec node --stack-size=10000 ./scripts/sync.js index check
+    ;;
+
+  *)
+    exec "$@"
+    ;;
+esac
@@ -0,0 +1,11 @@
+#!/bin/bash
+# Creates the explorer app user in explorerdb.
+# Runs once on first container start (only when the data volume is empty).
+mongosh -u "$MONGO_INITDB_ROOT_USERNAME" -p "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin <<EOF
+use $MONGO_APP_DB
+db.createUser({
+  user: "$MONGO_APP_USER",
+  pwd:  "$MONGO_APP_PASS",
+  roles: [{ role: "readWrite", db: "$MONGO_APP_DB" }]
+})
+EOF
@@ -0,0 +1,227 @@
+{
+  "locale": "locale/en.json",
+
+  "dbsettings": {
+    "user": "${MONGO_USER}",
+    "password": "${MONGO_PASSWORD}",
+    "database": "${MONGO_DATABASE}",
+    "address": "${MONGO_HOST}",
+    "port": "${MONGO_PORT}"
+  },
+
+  "wallet": {
+    "host": "${WALLET_RPC_HOST}",
+    "port": "${WALLET_RPC_PORT}",
+    "username": "${WALLET_RPC_USER}",
+    "password": "${WALLET_RPC_PASS}"
+  },
+
+  "webserver": {
+    "port": 3001,
+    "tls": {
+      "enabled": false,
+      "port": 443,
+      "always_redirect": false,
+      "cert_file": "",
+      "chain_file": "",
+      "key_file": ""
+    },
+    "cors": {
+      "enabled": false,
+      "corsorigin": "*"
+    }
+  },
+
+  "coin": {
+    "name": "${COIN_NAME}",
+    "symbol": "${COIN_SYMBOL}"
+  },
+
+  "network_history": {
+    "enabled": true,
+    "max_saved_records": 0,
+    "max_hours": 24
+  },
+
+  "shared_pages": {
+    "theme": "${EXPLORER_THEME}",
+    "page_title": "${COIN_NAME} Explorer",
+    "favicons": {
+      "favicon32": "favicon-32.png",
+      "favicon128": "favicon-128.png",
+      "favicon180": "favicon-180.png",
+      "favicon192": "favicon-192.png"
+    },
+    "logo": "/img/logo.png",
+    "date_time": {
+      "display_format": "LLL dd, yyyy HH:mm:ss ZZZZ",
+      "timezone": "utc",
+      "enable_alt_timezone_tooltips": false
+    },
+    "table_header_bgcolor": "",
+    "confirmations": 6,
+    "difficulty": "${COIN_DIFFICULTY}",
+    "show_hashrate": true,
+    "page_header": {
+      "menu": "side",
+      "sticky_header": true,
+      "bgcolor": "",
+      "home_link": "coin",
+      "home_link_logo": "",
+      "home_link_logo_height": 50,
+      "panels": {
+        "network_panel": {
+          "enabled": true,
+          "display_order": 1,
+          "nethash": "getnetworkhashps",
+          "nethash_units": "G"
+        },
+        "difficulty_panel": {
+          "enabled": true,
+          "display_order": 2
+        },
+        "masternodes_panel": {
+          "enabled": false,
+          "display_order": 0
+        },
+        "coin_supply_panel": {
+          "enabled": true,
+          "display_order": 3
+        },
+        "price_panel": {
+          "enabled": false,
+          "display_order": 0,
+          "coingecko_id": ""
+        }
+      },
+      "block_count_panel": {
+        "enabled": true,
+        "display_order": 4
+      },
+      "custom_menus": []
+    },
+    "page_footer": {
+      "enabled": true,
+      "bgcolor": "",
+      "shortcut_menus": []
+    },
+    "search": {
+      "enabled": true
+    }
+  },
+
+  "index_page": {
+    "show_panels": true,
+    "show_nethash_chart": true,
+    "show_difficulty_chart": true,
+    "page_header": {
+      "show_panels": true,
+      "show_nethash_chart": true,
+      "show_difficulty_chart": true
+    },
+    "transaction_count": 20
+  },
+
+  "block_page": {
+    "show_panels": false,
+    "genesis_block": "0000000000000000000000000000000000000000000000000000000000000000"
+  },
+
+  "transaction_page": {
+    "show_panels": false,
+    "show_unconfirmed_warning_banner": true
+  },
+
+  "address_page": {
+    "show_panels": false,
+    "enable_hidden_address_view": false,
+    "enable_claim_address_feature": false
+  },
+
+  "richlist_page": {
+    "show_panels": false,
+    "enabled": true,
+    "show_received_column": true,
+    "show_balance_column": true,
+    "show_percent_column": true,
+    "show_sent_column": false
+  },
+
+  "movement_page": {
+    "show_panels": false,
+    "enabled": true,
+    "min_amount": 100,
+    "low_supply": false
+  },
+
+  "network_page": {
+    "show_panels": false,
+    "enabled": true,
+    "nethash_chart": {
+      "enabled": true,
+      "chart_days": 30
+    },
+    "difficulty_chart": {
+      "enabled": true,
+      "chart_days": 30
+    }
+  },
+
+  "masternodes_page": {
+    "show_panels": false,
+    "enabled": false
+  },
+
+  "markets_page": {
+    "show_panels": false,
+    "enabled": false,
+    "default_exchange": "",
+    "default_exchange_currency": "",
+    "exchanges": {}
+  },
+
+  "api_page": {
+    "show_panels": false,
+    "enabled": true,
+    "public_apis": {
+      "rpc": {
+        "getdifficulty": { "enabled": true },
+        "getconnectioncount": { "enabled": true },
+        "getblockcount": { "enabled": true },
+        "getblockhash": { "enabled": true },
+        "getblock": { "enabled": true },
+        "getrawtransaction": { "enabled": true },
+        "getnetworkhashps": { "enabled": true }
+      },
+      "ext": {
+        "getmoneysupply": { "enabled": true },
+        "getdistribution": { "enabled": true },
+        "getaddress": { "enabled": true },
+        "getaddresstxs": { "enabled": true },
+        "gettx": { "enabled": true },
+        "getbalance": { "enabled": true },
+        "getlasttxs": { "enabled": true },
+        "getcurrentprice": { "enabled": true },
+        "getnetworkpeers": { "enabled": true },
+        "getbasicstats": { "enabled": true },
+        "getsummary": { "enabled": true },
+        "getmasternodelist": { "enabled": false },
+        "getmasternodecount": { "enabled": false }
+      }
+    },
+    "api_rate_limit": {
+      "enabled": true,
+      "limit_safe_count": 15,
+      "limit_expensive_count": 5
+    }
+  },
+
+  "orphans_page": {
+    "show_panels": false,
+    "enabled": true
+  },
+
+  "sync": {
+    "block_parallel_tasks": 1
+  }
+}