Skip to content

comassky/btc-node-dashboard

BranchesTags

Repository files navigation

Bitcoin Node Dashboard ₿

Monitor your Bitcoin Core node in real-time with a modern web interface.

License Java Quarkus Vue TypeScript

📸 Screenshots

image

✨ Features

  • Reactive & Non-blocking Backend (Mutiny): Ultra-responsive, event-driven backend using Quarkus and Mutiny for maximum scalability.
  • Parallel & Monitored RPC Execution: All Bitcoin Core RPC calls are executed in parallel, with DEBUG logs and latency measurement for each call.
  • Advanced Caching: Prevents redundant RPC calls by caching ongoing requests, with fine-tuned expiry and buffer (see dashboard.cache.*).
  • Configurable & Nested Dashboard Settings: All dashboard features are configurable via nested properties (see dashboard.*), compatible with Quarkus @ConfigMapping and @WithName.
  • Live Peer & Network Statistics: Real-time display of inbound/outbound connections, peer details, version and geographic distribution.
  • Blockchain & Mempool Monitoring: Track block height, sync progress, node uptime, mempool size, and network health in real time.
  • Modern UI/UX: Dark/light/gray mode, responsive design, interactive charts, glassmorphism effects, optimized icons (official Tor logo, network-specific icons).
  • WebSocket Streaming: Instant dashboard updates, automatic reconnection, exponential backoff, session cleanup.
  • Mock/Test Mode: Simulate errors, low peer count, disconnected mode for testing and demos.
  • Comprehensive Error Handling: Clear user messages, automatic recovery and reconnection.
  • Security & Privacy: No tracking, no analytics, all data stays on your node.
  • Performance Optimized: GraalVM Native (<50ms startup, ~30MB RAM), Chart.js tree-shaking, optimized component rendering (1375+ fewer instances), gzip/brotli compression (144KB), reusable composables.
  • Docker & CI/CD Ready: Easy deployment, optimized images, automated builds and tests (GitHub Actions).
  • Composable Architecture: Reusable Vue composables (useSortableTable, usePeerAnalytics) for clean, maintainable code.

🛠️ Tech Stack

Backend

Technology Version Description
Java 25 Programming language
Quarkus 3.31.0.CR1 Reactive Java framework
Mutiny (via Quarkus BOM) Reactive programming library
Jakarta WebSocket - Real-time communication
MicroProfile REST Client - HTTP client for Bitcoin RPC
Jackson - JSON processing
Caffeine Cache - High-performance async cache
SmallRye OpenAPI - OpenAPI/Swagger documentation

Frontend

Runtime Dependencies

Technology Version Description
Vue.js 3.5.26 Progressive JavaScript framework
VueUse 14.1.0 Composition utilities
Pinia 3.0.4 State management
Chart.js 4.5.1 Interactive charts (tree-shaken)
Iconify 5.0.0 Icon framework
Simple Icons 1.2.65 Brand logos (Tor, etc.)
Floating UI 1.1.9 Tooltip positioning
date-fns 4.1.0 Date utilities
filesize 11.0.13 File size formatting

Build Tools

Technology Version Description
TypeScript 5.9.3 Type-safe JavaScript
Vite 7.3.1 Build tool & dev server
Tailwind CSS 4.1.18 Utility-first CSS framework
Vitest 4.0.16 Unit testing framework
Prettier 3.7.4 Code formatter

Build & Deploy

  • Maven 3.9.11 (Backend build and dependency management)
  • Maven Compiler Plugin 3.14.1
  • Maven Surefire Plugin 3.5.4
  • Maven Failsafe Plugin 3.5.4
  • Frontend Maven Plugin 2.0.0
  • Node.js v24.12.0 (via Maven)
  • pnpm 10.28.2 (Frontend package manager, recommended)
  • npm 11.6.2 (Alternative package manager)
  • Docker (JVM & GraalVM Native images)
  • GitHub Actions (CI/CD with automated testing and native image builds)
  • GraalVM Native Image (AOT compilation for ultra-fast startup)

🧪 Automated Tests

Suite Tests
Backend 79
Frontend 83

Total: 162 tests ensuring code quality and stability.

🏎️ Recommended Native Build (GraalVM)

For maximum performance (startup <50ms, RAM ~30MB), use the Quarkus native build:

mvn package -Pnative -DskipTests
# or with Docker
mvn package -Pnative -Dquarkus.native.container-build=true -DskipTests

The native Docker image is generated with Dockerfile.native:

docker build -f Dockerfile.native -t btc-node-dashboard-native .
docker run -p 8080:8080 btc-node-dashboard-native

The native binary starts instantly and uses very little memory, making it ideal for production.

🚀 Quick Start

Prerequisites

  • Java 25+ and Maven 3.9+ (Maven Wrapper included: ./mvnw)
  • Bitcoin Core with RPC enabled
  • Node.js 24+ (optional, for frontend development)

Développement

git clone https://github.com/comassky/btc-node-dashboard.git
cd btc-node-dashboard

# Configurez le backend (variables d'environnement ou application-local.properties)
export BITCOIN_RPC_HOST=localhost
export BITCOIN_RPC_PORT=8332
export BITCOIN_RPC_USER=your_user
export BITCOIN_RPC_PASSWORD=your_password

# Installez les dépendances frontend (recommandé : pnpm)
cd src/main/web
pnpm install
# ou, si pnpm n'est pas installé :
npm install -g pnpm@10.27.0
pnpm install

# Démarrez le serveur de développement frontend (Vite)
pnpm dev
# ou npm run dev

# Dans un autre terminal, démarrez le backend avec hot reload
cd ../..
./mvnw quarkus:dev  # http://localhost:8080

🐳 Docker (Recommended)

# Run native GraalVM image (fast startup, low memory)
docker run -d -p 8080:8080 \
  -e BITCOIN_RPC_HOST=<HOST> \
  -e BITCOIN_RPC_PORT=<PORT> \
  -e BITCOIN_RPC_USER=<USER> \
  -e BITCOIN_RPC_PASSWORD=<PASSWORD> \
  -e WS_POLLING_INTERVAL=5 \
  -e MIN_OUTBOUND_PEERS=8 \
  -e LOG_LEVEL=INFO \
  -e DASHBOARD_CACHE_VALIDITY_BUFFER_MS=200 \
  ghcr.io/comassky/btc-node-dashboard:native

Docker images are built and published automatically via GitHub Actions workflows:

  • docker-native.yml (Native)
  • docker-dev-native.yml (develop branch)

Image Performance

Metric Native
Startup ~50-80ms
Memory ~30-60MB
Image Size ~120MB
CPU (Idle) <0.5%

See DOCKER.md for more details.

Available Image Tags

A short summary of the Docker image tags produced by the GitHub Actions workflows (full list in DOCKER.md):

  • latest and semantic version tags (<version>, <major>.<minor>, <major>): native (GraalVM) images built from main and from git tags.
  • develop: images built from the develop branch.
  • Current version: 1.5.0

📊 API Endpoints

REST API

The backend exposes RESTful endpoints to retrieve Bitcoin node data.

📖 OpenAPI Specification: Available at project root as openapi.json and openapi.yaml (versioned)

➡️ OpenAPI YAML documentation ➡️ OpenAPI JSON documentation

The API specification follows the OpenAPI 3.0 standard and documents all available endpoints, request/response schemas, and parameters.

Available Endpoints

  • GET /api/config — Get dashboard configuration (e.g., minOutboundPeers)
  • GET /api/dashboard — Get aggregated dashboard data (GlobalResponse)
  • GET /api/getnetworkinfo — Get node network information
  • GET /api/getblock/{hash} — Get block information by hash
  • GET /api/getbestblockhash — Get the hash of the best block (plain text)
  • GET /api/getBlockchainInfo — Get blockchain information
  • GET /api/getmempoolinfo — Get mempool information
  • GET /api/blockchaininfo — Get blockchain information (BlockchainInfo)
  • GET /api/cache/stats — Get cache performance statistics (reactive)
  • GET /api/getmempoolinfo — Get mempool information

WebSocket

  • WS /ws/dashboard — Real-time dashboard updates

🔧 Configuration

For details on reactive programming, non-blocking guarantees and contribution guidelines, see CONTRIBUTING.md.

Environment Variables

  • QUARKUS_IO_THREADS: Number of IO threads for the backend (recommended: 2 × number of CPU cores). Set this environment variable to control backend concurrency. Example: QUARKUS_IO_THREADS=16 java -jar .... Defaults to 8 if not set.

  • BITCOIN_RPC_HOST, BITCOIN_RPC_PORT, BITCOIN_RPC_USER, BITCOIN_RPC_PASSWORD: Bitcoin node connection

  • WS_POLLING_INTERVAL: dashboard refresh interval (seconds)

  • MIN_OUTBOUND_PEERS: minimum outbound peers

  • DASHBOARD_CACHE_VALIDITY_BUFFER_MS: cache validity buffer (ms)

  • LOG_LEVEL: log level (INFO, DEBUG, ...)

For the complete list and default values, see BUILD.md.

🧩 Monorepo & pnpm workspace

The project uses a pnpm workspace for frontend dependency management. See src/main/web/pnpm-workspace.yaml.

To install all dependencies:

cd src/main/web
pnpm install

Example in application-local.properties:

bitcoin.rpc.host=localhost
bitcoin.rpc.port=8332
bitcoin.rpc.user=your_user
bitcoin.rpc.password=your_password
dashboard.polling.interval.seconds=5
dashboard.cache.validity.buffer.ms=200

🚦 Build & Continuous Integration

  • The Maven build (mvn package) runs all tests and produces the final artifact (backend + frontend bundled).
  • Native Docker workflows use this artifact: no build or tests are repeated in those steps.
  • CI (GitHub Actions) blocks any deployment if a test fails.
  • See BUILD.md and TESTING.md for more details.

🎨 Frontend Development

See BUILD.md for detailed instructions on setting up and running the frontend development server, as well as building the frontend.

🤝 Contributing

Contributions are welcome! Fork, branch, commit, push, and open a pull request.

Cryptocurrency Donations

Currency Address
Bitcoin (BTC) bc1qa7kcf6r9xemdmcs7wufufztfcl7rzravx9naz3
Ethereum / BSC (ETH) 0x0f26B8Bdc028F6bd0F79FF4959306065C36d5EAa
Solana (SOL) FH7HPraEeSva72g5Cv2WTbP65tPxQiZc1GNCSk2ML7eN

Lightning Network ⚡

Lightning Network QR Code

Every satoshi helps keep this project maintained and growing!

Your support enables continuous improvements, new features, and better documentation.

🙏 Acknowledgments

Built with Quarkus, Vue.js, Tailwind CSS, Chart.js, and Bitcoin Core.

Built with ❤️ for the Bitcoin community

About

Real-time Bitcoin node dashboard with WebSocket streaming. Quarkus + Vue.js. GraalVM native support: <25ms startup, ~30MB RAM. Monitors peers, blockchain stats & network metrics via RPC.

Resources

Readme

License

GPL-3.0 license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 8

1.5.0 Latest
Feb 24, 2026
+ 7 releases

Packages

 
 
 

Contributors

Languages