purple-explorer/README.md

BitcoinPurple Explorer

Fork of team-exor/eiquidus Customized for the BitcoinPurple blockchain.

Designed to run alongside 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)

---

Quick Start (Docker)

Prerequisites: Docker, Docker Compose, and the purple Docker network already running (created by the purple-stack that runs bitcoinpurpled).

# 1. Copy and fill in the env file
cp .env.example .env
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
#    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 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 (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)

To run a full reindex from genesis:

docker compose run --rm explorer reindex

Configuration

All settings are injected at container start via docker/settings.json.tmpl + environment variables. Copy .env.example to .env and set at minimum:

Variable	Description
WALLET_RPC_USER	rpcuser from bitcoinpurple.conf
WALLET_RPC_PASS	rpcpassword from bitcoinpurple.conf
MONGO_PASSWORD	Password for the MongoDB app user
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).

Docker Management

# Start / stop all services
docker compose up -d
docker compose down

# Rebuild after code changes
docker compose up -d --build

# View logs
docker logs -f purple-explorer
docker logs -f purple-explorer-sync-blocks

# Open a shell inside the explorer container
docker exec -it purple-explorer sh

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.

Stop MongoDB first to ensure a consistent snapshot, then archive the ./db directory:

docker stop purple-explorer-mongodb
sudo tar -czf ~/purple-explorer/db_backup_$(date +%Y-%m-%d).tar.gz -C ~/purple-explorer db
docker start purple-explorer-mongodb

Wallet Settings

The bitcoinpurpled wallet must be running with the following options in bitcoinpurple.conf:

daemon=1
txindex=1

In most cases the blockchain must be synced with txindex=1 enabled to have access to all transactions.

CORS Support

eIquidus has basic CORS support which is useful to prevent other sites from consuming public APIs while still allowing specific websites whitelisted access.

Enable CORS by editing docker/settings.json.tmpl and setting webserver.cors.enabled to true. Set webserver.cors.corsorigin to the specific origin you want to allow (defaults to "*" which allows all origins — not recommended for production):

"webserver": {
  "cors": {
    "enabled": true,
    "corsorigin": "https://example.com"
  }
}

Known Issues

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.

Special Thanks

• Luke Williams (aka iquidus): for creating the original Iquidus explorer
• Alan Rudolf (aka suprnurd): for the custom changes found in the Ciquidus explorer
• Tim Garrity (aka uaktags): for his many contributions to the Iquidus explorer
• TheHolyRoger: for his continued work and contributions to the Iquidus explorer
• Team Exor: for the eIquidus explorer this fork is based on
• All the rest of the Iquidus contributors who helped shape the Iquidus explorer

License

Copyright (c) 2019-2025, The Exor Community
Copyright (c) 2017, The Chaincoin Community
Copyright (c) 2015, Iquidus Technology
Copyright (c) 2015, Luke Williams
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of Iquidus Technology nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.