diff --git a/README.md b/README.md index faea6bf..ed2bc6a 100644 --- a/README.md +++ b/README.md @@ -5,67 +5,21 @@ ![GitHub](https://img.shields.io/github/license/team-exor/eiquidus?color=7c3aed) +> **Designed to run alongside [purple-stack](https://github.com/BitcoinPurpleBlockchain/purple-stack).** +> That repository provides the `bitcoinpurpled` node and creates the shared `purple` Docker network that this explorer connects to. Start `purple-stack` first, then bring up this explorer. + ### BitcoinPurple Customizations The following changes were made on top of the upstream eIquidus codebase: - **Docker Compose stack** — `Dockerfile`, `docker-compose.yml`, `docker/entrypoint.sh`, `docker/settings.json.tmpl`: single image supporting `web`, `sync-blocks`, and `sync-peers` run modes; joins the external `purple` Docker network to reach the `bitcoinpurpled` RPC at `bitcoinpurpled:13495`; MongoDB runs in an isolated internal network +- **Caddy reverse proxy** — automatic HTTPS via Let's Encrypt; domain configurable via `DOMAIN` in `.env` - **Coin supply via TXOUTSET** — BitcoinPurple has no `getinfo` RPC; supply is fetched via `gettxoutsetinfo` (`sync.supply: "TXOUTSET"` in settings) - **Purple/violet dark theme** — `public/css/themes/purple/` + `public/css/custom.scss`: high-contrast 4-level luminance palette, pill-shaped search bar, glowing stat panels, styled chart cards - **Hashrate auto-scaling** — `public/js/custom.js`: the network hashrate panel and chart Y-axis auto-scale to keep values in the 1–999 range with the correct unit (H/s → KH/s → MH/s → GH/s → TH/s → PH/s) --- -Written in node.js and mongodb, eIquidus is the most stable, secure, customizable and feature-rich open-source block explorer with support for virtually any altcoin that implements some form of the [Bitcoin RPC API protocol](https://developer.bitcoin.org/reference/rpc/index.html) (EVM blockchains such as ETH, BNB, etc. are not supported). Originally built for the [Exor blockchain](https://github.com/team-exor/exor), eIquidus has since grown into a fully-featured explorer with a focus on stability and security at its core. All features from the [original iquidus explorer](https://github.com/iquidus/explorer) are included here along with many new ideas from other iquidus forks, and an absolute ton of new custom changes and bug fixes that were developed specifically for eIquidus. - -Table of Contents ------------------- - -- [Features](#features) -- [Quick Start (Docker)](#quick-start-docker) -- [Configuration](#configuration) -- [Docker Management](#docker-management) -- [Backup & Restore](#backup--restore) -- [Wallet Settings](#wallet-settings) -- [CORS Support](#cors-support) -- [Known Issues](#known-issues) -- [Special Thanks](#special-thanks) -- [License](#license) - -### Features - -- Built using the following scripts and technologies: - - Node.js (v20.9.0 or newer recommended) - - MongoDB (v7.0.2 or newer recommended) - - jQuery v3.7.1 - - Bootstrap v5.1.3 - - DataTables v1.13.6 - - Font Awesome v6.4.2 - - Luxon v3.4.3 - - Chart.js v4.4.7 - - chartjs-plugin-crosshair v2.0.5 - - chartjs-chart-financial v0.1.1 - - chartjs-adapter-luxon v1.3.1 - - chartjs-plugin-annotation v3.1.0 - - OverlayScrollbars v2.3.2 - - flag-icons v6.11.1 -- Mobile-friendly -- Multi-threaded block sync -- Sass support -- Pages/features: - - **Home/Explorer:** Displays latest blockchain transactions - - **Movement:** Displays latest blockchain transactions greater than a configurable amount - - **Network:** Displays peers that connected to the node in the past 24 hours - - **Top 100:** Richest wallet addresses and wealth distribution chart - - **API:** Public REST APIs for block data, address balances, network stats, and more - - **Orphaned Blocks:** List of orphaned blocks with links to neighboring valid blocks - - **Block Info:** Block summary and transaction list for a specific block height - - **Transaction Info:** Input/output addresses, OP_RETURN value, coinbase info - - **Address Info:** Balance, total sent/received, QR code, and transaction history -- Choose from 26 built-in Bootswatch themes plus the custom **Purple** theme included in this fork -- Configurable network charts (hashrate and difficulty) displayed in the page header -- Custom social links in the footer - ### Quick Start (Docker) **Prerequisites:** Docker, Docker Compose, and the `purple` Docker network already running (created by the `purple-stack` that runs `bitcoinpurpled`). @@ -73,24 +27,27 @@ Table of Contents ```bash # 1. Copy and fill in the env file cp .env.example .env -nano .env # set WALLET_RPC_USER, WALLET_RPC_PASS, MONGO_PASSWORD +nano .env # set WALLET_RPC_USER, WALLET_RPC_PASS, MONGO_PASSWORD, DOMAIN # 2. Build the image and start all services docker compose up -d --build # 3. Check that the web explorer is up -curl http://localhost:3001 +# Dev (DOMAIN=localhost): http://localhost +# Prod (DOMAIN=your.domain.com): https://your.domain.com +curl http://localhost # 4. Watch the block sync log docker logs -f purple-explorer-sync-blocks ``` -The stack starts four containers: +The stack starts five containers: | Container | Role | |---|---| +| `purple-explorer-caddy` | Caddy reverse proxy — ports 80/443, automatic HTTPS via Let's Encrypt | | `purple-explorer-mongodb` | MongoDB 7 (internal network only) | -| `purple-explorer` | Web UI on port 3001 | +| `purple-explorer` | Web UI on port 3001 (internal only, proxied by Caddy) | | `purple-explorer-sync-blocks` | Syncs blocks every `SYNC_BLOCKS_INTERVAL` seconds (default 120) | | `purple-explorer-sync-peers` | Syncs peers every `SYNC_PEERS_INTERVAL` seconds (default 300) | @@ -109,7 +66,7 @@ All settings are injected at container start via `docker/settings.json.tmpl` + e | `WALLET_RPC_USER` | `rpcuser` from `bitcoinpurple.conf` | | `WALLET_RPC_PASS` | `rpcpassword` from `bitcoinpurple.conf` | | `MONGO_PASSWORD` | Password for the MongoDB app user | -| `EXPLORER_PORT` | Host port for the web UI (default `3001`) | +| `DOMAIN` | Domain served by Caddy. Use `localhost` for local development (HTTP, no certificate needed). Use a real domain for production — Caddy will obtain a Let's Encrypt certificate automatically. | You can further customize the site by adding javascript to `public/js/custom.js` and CSS rules to `public/css/custom.scss`. Changes to these files require rebuilding the image (`docker compose up -d --build`). @@ -131,12 +88,10 @@ docker logs -f purple-explorer-sync-blocks docker exec -it purple-explorer sh ``` -### Backup & Restore +### Backup MongoDB's data files are stored in the `./db` directory (bind-mounted into the container). Because the files are owned by the MongoDB process (root inside the container), `sudo` is required. -#### Create a backup - Stop MongoDB first to ensure a consistent snapshot, then archive the `./db` directory: ```bash @@ -145,15 +100,6 @@ sudo tar -czf ~/purple-explorer/db_backup_$(date +%Y-%m-%d).tar.gz -C ~/purple-e docker start purple-explorer-mongodb ``` -#### Restore a backup - -```bash -docker stop purple-explorer-mongodb -sudo rm -rf ~/purple-explorer/db/* -sudo tar -xzf ~/purple-explorer/db_backup_YYYY-MM-DD.tar.gz -C ~/purple-explorer -docker start purple-explorer-mongodb -``` - ### Wallet Settings The `bitcoinpurpled` wallet must be running with the following options in `bitcoinpurple.conf`: @@ -182,10 +128,6 @@ Enable CORS by editing `docker/settings.json.tmpl` and setting `webserver.cors.e ### Known Issues -**Error: bind EACCES ...** - -This error appears when trying to run the explorer on a port lower than 1024 without root permissions. In the Docker setup this is not an issue since the internal port is always 3001; use a reverse proxy (e.g. Caddy) on the host to expose port 80/443. - **Error: Callback was already called** Typically a connection issue between the explorer and the wallet daemon. The most common cause is configuring the P2P port instead of the RPC port in the settings. Also check that `bitcoinpurpled` is running and accepting RPC connections.