davide/palladium-stack
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
palladium-stack/README.md

22 KiB
Raw Permalink Blame History

ElectrumX Server with Palladium (PLM) Full Node

Complete Dockerized setup for running an ElectrumX server with an integrated Palladium (PLM) full node and professional Web Dashboard for monitoring.

Everything runs in Docker containers - no need to install dependencies on your host system!

What You Get

  • Palladium Full Node (palladiumd) - Runs in Docker with full blockchain sync (binary setup)
  • ElectrumX Server - Pre-configured for Palladium network with automatic indexing
  • Web Dashboard - Professional monitoring interface with real-time statistics, peer views, and Electrum server discovery (quick start | technical docs)
  • Automatic RPC Configuration - ElectrumX reads credentials directly from palladium.conf
  • Self-Signed SSL Certificates - Auto-generated on first startup, persisted in ./certs/
  • Public IP Auto-Detection - Automatically configures REPORT_SERVICES and SSL certificate SAN
  • Production Ready - Includes restart policies, health endpoint, and Basic Auth for external dashboard access

Tested Platforms

  • Debian 12/13
  • Ubuntu 24.04/22.04 LTS
  • Raspberry Pi OS (ARM64)
  • WSL2 (Windows Subsystem for Linux)

System Requirements:

  • 64-bit system (AMD64 or ARM64)
  • 4GB+ RAM recommended
  • 50GB+ free disk space for blockchain
  • Stable internet connection

Project Structure

palladium-stack/
├── daemon/                          # Palladium binaries (YOU must add these)
│   ├── palladiumd                   # Node daemon (required)
│   ├── palladium-cli                # CLI tool (required)
│   ├── palladium-tx                 # Transaction tool (optional)
│   ├── palladium-wallet             # Wallet tool (optional)
│   └── README.md                    # Binary download instructions
├── .palladium/
│   ├── palladium.conf               # Node configuration (edit this!)
│   ├── blocks/                      # Blockchain blocks (auto-generated)
│   ├── chainstate/                  # Blockchain state (auto-generated)
│   └── ...                          # Other runtime data (auto-generated)
├── certs/                           # SSL certificates (auto-generated on first run)
│   ├── server.crt                   # Self-signed certificate
│   └── server.key                   # Private key
├── electrumx-data/                  # ElectrumX database (auto-generated)
├── electrumx-patch/
│   └── coins_plm.py                 # Palladium coin definition for ElectrumX
├── web-dashboard/                   # Web monitoring dashboard
│   ├── app.py                       # Flask backend API
│   ├── templates/                   # HTML templates
│   ├── static/                      # CSS and JavaScript
│   └── README.md                    # Dashboard technical docs
├── Dockerfile.palladium-node        # Builds Palladium node container
├── Dockerfile.electrumx             # Builds ElectrumX server container
├── Dockerfile.dashboard             # Builds web dashboard container
├── docker-compose.yml               # Main orchestration file
├── entrypoint.sh                    # ElectrumX startup (auto-config, SSL, IP detection)
├── test-server.py                   # ElectrumX protocol test client
├── .env.example                     # Environment variables template
└── DASHBOARD.md                     # Dashboard quick start guide

Palladium Full Node: palladium-coin/palladiumcore

Architecture

Internet                Router/Firewall           Docker Network
   │                          │                          │
   │                    ┌─────▼──────┐                   │
   │                    │  Port      │                   │
   │    P2P (2333) ────►│  Forward   │──────────┐        │
   │    TCP (50001)────►│  Rules     │────┐     │        │
   │    SSL (50002)────►│            │──┐ │     │        │
   │    Web (8080) ────►│            │─┐│ │     │        │
   │                    └────────────┘ ││ │     │        │
   │                                   ││ │     │        │
   │                         ┌─────────▼▼─▼─────▼─────┐  │
   │                         │   Docker Host          │  │
   │                         │                        │  │
   │                         │  ┌───────────────────┐ │  │
   │                         │  │  Palladium Node   │ │  │
   │                         │  │   (palladiumd)    │ │  │
   │                         │  │   Port: 2333      │ │  │
   │                         │  └────────┬──────────┘ │  │
   │                         │           │            │  │
   │                         │  ┌────────▼──────────┐ │  │
   │                         │  │  ElectrumX Server │ │  │
Clients◄────────────────────────┤  TCP: 50001       │ │  │
(Electrum                    │  │  SSL: 50002       │ │  │
 Wallets)                    │  └────────┬──────────┘ │  │
   │                         │           │            │  │
   │                         │  ┌────────▼─────────┐  │  │
   ▼                         │  │  Web Dashboard   │  │  │
Browser◄───────────────────────┤  Port: 8080       │  │  │
                             │  └──────────────────┘  │  │
                             └────────────────────────┘  │

Component Communication:

  • ElectrumX ↔ Palladium Node: RPC over internal Docker network
  • Web Dashboard ↔ Palladium Node: RPC for blockchain data
  • Web Dashboard ↔ ElectrumX: Electrum protocol + Docker API for stats
  • External Clients → ElectrumX: TCP (50001) or SSL (50002)
  • Browsers → Web Dashboard: HTTP (8080)

Requirements

Quick Start Guide

Step 1: Clone the Repository

git clone <your-repository-url>
cd palladium-stack

Step 2: Get Palladium Binaries

IMPORTANT: Download binaries matching your system architecture in daemon/.

See daemon/README.md for detailed instructions.

Step 3: Configure Network and Router

3.1 Configure RPC Credentials

Open the configuration file:

nano .palladium/palladium.conf

Change these credentials:

rpcuser=your_username     # ← Change this
rpcpassword=your_password # ← Use a strong password!

Save and close (Ctrl+X, then Y, then Enter).

3.2 Router Port Forwarding (Required for Public Access)

For your ElectrumX server to be accessible from the internet, you must configure port forwarding on your router.

Ports to Forward:

Port Protocol Service Description Required?
2333 TCP Palladium P2P Node connections Yes (for node sync)
50001 TCP ElectrumX TCP Wallet connections Recommended
50002 TCP ElectrumX SSL Encrypted wallet connections Recommended
8080 TCP Web Dashboard Monitoring interface Optional

How to Configure Port Forwarding:

  1. Find Your Internal IP:

    # Linux/Mac:
hostname -I

# Or check in Docker host:
ip addr show

    Example: 192.168.1.100

  2. Access Your Router:

    • Open browser and go to your router's admin page (usually 192.168.1.1 or 192.168.0.1)
    • Login with router credentials

  3. Add Port Forwarding Rules:

    Navigate to Port Forwarding or Virtual Server section and add:

    Service Name: Palladium P2P
External Port: 2333
Internal Port: 2333
Internal IP: 192.168.1.100 (your server's IP)
Protocol: TCP

Service Name: ElectrumX SSL
External Port: 50002
Internal Port: 50002
Internal IP: 192.168.1.100
Protocol: TCP

Service Name: ElectrumX TCP
External Port: 50001
Internal Port: 50001
Internal IP: 192.168.1.100
Protocol: TCP

Service Name: PLM Dashboard (optional)
External Port: 8080
Internal Port: 8080
Internal IP: 192.168.1.100
Protocol: TCP

  4. Save and Apply the configuration.

  5. Find Your Public IP:

    curl ifconfig.me

    Or visit: https://whatismyipaddress.com

Security Notes:

  • Only forward port 8080 if you want the dashboard accessible from internet (not recommended without authentication)
  • Consider using a VPN for dashboard access instead
  • External dashboard clients (public IPs) require Basic Auth. Configure DASHBOARD_AUTH_USERNAME and DASHBOARD_AUTH_PASSWORD in .env (see .env.example).
  • Ports 50001 and 50002 need to be public for Electrum wallets to connect
  • Port 2333 is required for the node to sync with the Palladium network

3.3: (Optional) Configure Dashboard Authentication

If you plan to expose the dashboard to the internet (port 8080), configure Basic Auth credentials:

cp .env.example .env
nano .env

Set strong credentials:

DASHBOARD_AUTH_USERNAME=admin
DASHBOARD_AUTH_PASSWORD=a-strong-random-password

LAN clients (private IPs) can access the dashboard without authentication. External clients (public IPs) will be prompted for these credentials automatically.

Step 4: (Optional) Copy Existing Blockchain Data

If you have a synced Palladium blockchain, copy it to speed up initial sync:

cp -r ~/.palladium/blocks .palladium/
cp -r ~/.palladium/chainstate .palladium/
cp -r ~/.palladium/indexes .palladium/

Skip this if syncing from scratch - the node will automatically start syncing.

Step 5: Build and Start

docker compose up -d

What happens:

  1. Builds three Docker images: palladium-node, electrumx-server, and palladium-dashboard
  2. Starts Palladium node first
  3. Starts ElectrumX (waits for node to be ready, auto-generates SSL certificates in ./certs/ if not present)
  4. Starts Web Dashboard (connects to both services)

First build takes 5-10 minutes.

Step 6: Monitor Progress

# View all logs
docker compose logs -f

# View specific service
docker compose logs -f palladiumd
docker compose logs -f electrumx
docker compose logs -f dashboard

What to look for:

  • Palladium node: "UpdateTip" messages (syncing blockchain)
  • ElectrumX: "height X/Y" (indexing blocks)
  • Dashboard: "Running on http://0.0.0.0:8080"

Press Ctrl+C to exit log view (containers keep running).

Step 7: Access Web Dashboard

Local access:

http://localhost:8080

Network access:

http://<your-server-ip>:8080

From internet (if port 8080 forwarded):

http://<your-public-ip>:8080

The dashboard shows:

  • System resources (CPU, RAM, Disk)
  • Palladium node status (height, difficulty, connections, sync progress)
  • ElectrumX server stats (version, active servers, DB size, uptime, server IP, ports)
  • Mempool information (transactions, size, usage)
  • Recent blocks table
  • Network peers (click "Connections" to view detailed peer list)
  • Electrum active servers page (click "Active Servers")

Web Dashboard Features

See also: DASHBOARD.md for quick start | web-dashboard/README.md for technical details

Main Dashboard (http://localhost:8080)

System Monitoring:

  • Real-time CPU, Memory, and Disk usage with animated progress bars
  • Health status indicator with pulse animation

Palladium Node:

  • Block Height (formatted with thousands separator: 380,050)
  • Difficulty (abbreviated: 18.5 M)
  • Connections (clickable - opens dedicated peers page)
  • Network type (MAINNET/TESTNET)
  • Sync Progress percentage
  • Node version (vX.X.X format)

ElectrumX Server:

  • Server Version
  • Database Size
  • Uptime
  • Active Servers (clickable to dedicated server list)
  • Server IP (for client configuration)
  • TCP Port (50001)
  • SSL Port (50002)

Mempool:

  • Transaction count
  • Total size (bytes)
  • Usage percentage
  • Max size limit

Recent Blocks:

  • Last 10 blocks with hash, time, size, and transaction count

Network Peers Page (http://localhost:8080/peers)

Statistics:

  • Total Peers count
  • Inbound connections
  • Outbound connections
  • Total traffic (sent + received)

Detailed Peer List:

  • IP Address and port
  • Direction (⬇️ Inbound / ⬆️ Outbound)
  • Node version
  • Connection time
  • Data sent
  • Data received
  • Total traffic per peer

Auto-refresh: Every 10 seconds

Electrum Active Servers Page (http://localhost:8080/electrum-servers)

Summary:

  • Total Active Servers
  • TCP 50001 Reachable

Detailed Server List:

  • Host
  • TCP Port
  • SSL Port
  • TCP Reachable (Yes/No)
  • SSL Reachable (Yes/No)

Servers are filtered by genesis hash to show only peers on the same network (mainnet or testnet).

Auto-refresh: Every 10 seconds

Verify Installation

Check Container Status

docker compose ps

Should show all three containers "Up".

Test Palladium Node

docker exec palladium-node palladium-cli \
  -rpcuser=<your_username> \
  -rpcpassword=<your_password> \
  getblockchaininfo

Test ElectrumX Server

python test-server.py <your-server-ip>:50002

Check from External Network

From another machine:

# Test dashboard
curl http://<your-public-ip>:8080

# Test ElectrumX (with Python)
python test-server.py <your-public-ip>:50002

REST API Endpoints

The dashboard exposes a REST API for programmatic access:

Endpoint Description
GET /api/health Service health check (palladium + electrumx status)
GET /api/system/resources CPU, memory, and disk usage
GET /api/palladium/info Node info (blockchain, network, mining, mempool)
GET /api/palladium/peers Detailed peer list with traffic stats
GET /api/palladium/blocks/recent Last 10 blocks
GET /api/electrumx/stats ElectrumX version, uptime, DB size, active servers
GET /api/electrumx/servers Discovered ElectrumX peers with reachability 
# Example
curl http://localhost:8080/api/health | jq

Configuration Details

Palladium Node Settings

Key settings in .palladium/palladium.conf:

Setting Value Purpose
rpcuser <your_username> RPC authentication
rpcpassword <your_password> RPC authentication
server=1 Required Enable RPC server
txindex=1 Required Index all transactions (ElectrumX needs this)
addressindex=1 Recommended Index addresses for fast queries
timestampindex=1 Recommended Index timestamps
spentindex=1 Recommended Index spent outputs
rpcbind=0.0.0.0 Required Allow Docker connections
rpcallowip=10.0.0.0/8 Recommended Allow private RFC1918 networks
rpcallowip=172.16.0.0/12 Recommended Allow private RFC1918 networks
rpcallowip=192.168.0.0/16 Recommended Allow private RFC1918 networks
port=2333 Default P2P network port (mainnet)
rpcport=2332 Default RPC port (mainnet)

ZeroMQ Ports (optional):

  • 28332 - Block hash notifications
  • 28333 - Transaction hash notifications
  • 28334 - Raw block data
  • 28335 - Raw transaction data

ElectrumX Settings

Configured in docker-compose.yml:

environment:
  COIN: "Palladium"        # Always "Palladium" for both networks
  NET: "mainnet"           # or "testnet"
  SERVICES: "tcp://0.0.0.0:50001,ssl://0.0.0.0:50002"
  # RPC credentials automatically read from palladium.conf

Automatic Configuration (via entrypoint.sh):

  • RPC credentials: Read automatically from mounted palladium.conf — no need to configure DAEMON_URL
  • Public IP detection: Discovers your public IP and sets REPORT_SERVICES for peer announcement
  • SSL certificates: Auto-generated on first startup in ./certs/ with SAN including localhost and public IP (see Security > SSL Certificates)
  • TX stats patching: Queries the live node for TX_COUNT / TX_COUNT_HEIGHT and patches the ElectrumX coin definition at startup
  • Single source of truth for credentials across all services

Network Support (Mainnet & Testnet)

Running on Mainnet (Default)

Default configuration is for mainnet - no changes needed.

Ports:

  • Palladium RPC: 2332
  • Palladium P2P: 2333
  • ElectrumX TCP: 50001
  • ElectrumX SSL: 50002

Switching to Testnet

  1. Edit palladium.conf:

    testnet=1
rpcport=12332

  2. Edit docker-compose.yml:

    environment:
  NET: "testnet"

  3. Clear database:

    docker compose down
rm -rf ./electrumx-data/*

  4. Restart:

    docker compose up -d

Testnet Ports:

  • Palladium RPC: 12332
  • Palladium P2P: 12333
  • ElectrumX: same (50001, 50002)

Common Commands

Container Management

# Start all services
docker compose up -d

# Stop all services
docker compose down

# Restart services
docker compose restart

# Restart specific service
docker compose restart electrumx

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

# View status
docker compose ps

# View resource usage
docker stats

Logs

# All logs (live)
docker compose logs -f

# Specific service
docker compose logs -f palladiumd
docker compose logs -f electrumx
docker compose logs -f dashboard

# Last 100 lines
docker compose logs --tail=100

# Since specific time
docker compose logs --since 30m

Palladium Node Commands

# Blockchain info
docker exec palladium-node palladium-cli \
  -rpcuser=USER -rpcpassword=PASS \
  getblockchaininfo

# Network info
docker exec palladium-node palladium-cli \
  -rpcuser=USER -rpcpassword=PASS \
  getnetworkinfo

# Peer count
docker exec palladium-node palladium-cli \
  -rpcuser=USER -rpcpassword=PASS \
  getconnectioncount

# Peer details
docker exec palladium-node palladium-cli \
  -rpcuser=USER -rpcpassword=PASS \
  getpeerinfo

Troubleshooting

Container Won't Start

Check logs:

docker compose logs <service-name>

Common issues:

  • Missing or incorrect RPC credentials
  • Port already in use
  • Insufficient disk space
  • Wrong architecture binaries

ElectrumX Can't Connect to Node

Verify:

  1. Node is running: docker compose ps
  2. RPC works: docker exec palladium-node palladium-cli -rpcuser=USER -rpcpassword=PASS getblockchaininfo
  3. Credentials match in palladium.conf

Slow Blockchain Sync

Tips:

  • Copy existing blockchain (Step 4)
  • Check internet speed
  • Verify addnodes in config
  • Be patient (initial sync takes hours/days)

Port Already in Use

# Check what's using port
sudo lsof -i :50001

# Kill process or change port in docker-compose.yml

Dashboard Shows Wrong Data

Force refresh:

  1. Clear browser cache (Ctrl+Shift+R)
  2. Check dashboard logs: docker compose logs dashboard
  3. Restart dashboard: docker compose restart dashboard

Binary Architecture Error

# Check your system
uname -m
# x86_64 = Intel/AMD 64-bit
# aarch64 = ARM 64-bit

# Check binary
file daemon/palladiumd
# Should match system architecture

# Fix: download correct binaries and rebuild
docker compose build --no-cache

Security Recommendations

Production Deployment

  1. Strong Credentials:

    • Use long, random passwords for RPC
    • Don't use default credentials

  2. Firewall Configuration:

    # Allow only required ports
sudo ufw allow 2333/tcp    # P2P
sudo ufw allow 50001/tcp   # ElectrumX TCP
sudo ufw allow 50002/tcp   # ElectrumX SSL
# Don't expose 8080 publicly without authentication
sudo ufw enable

  3. SSL Certificates:

    • Self-signed certificates are auto-generated on first startup in ./certs/
    • The certificate includes localhost and the auto-detected public IP in its SAN
    • To use your own certificates (e.g. Let's Encrypt), place server.crt and server.key in ./certs/ before starting

  4. Dashboard Access:

    • LAN clients (RFC1918 private IPs) can access without authentication
    • External clients (public IPs) require HTTP Basic Auth automatically
    • Configure credentials in .env (copy from .env.example): 
      DASHBOARD_AUTH_USERNAME=admin
DASHBOARD_AUTH_PASSWORD=a-strong-random-password
    • Consider using a VPN instead of exposing port 8080 publicly

  5. Regular Updates:

    # Update Palladium binaries
# Update Docker images
docker compose pull
docker compose up -d

  6. Monitoring:

    • Set up log monitoring
    • Monitor disk space
    • Watch for unusual activity in dashboard

Performance Tuning

System Resources

Minimum:

  • 2 CPU cores
  • 4GB RAM
  • 50GB storage

Recommended:

  • 4+ CPU cores
  • 8GB+ RAM
  • 100GB+ SSD storage

Docker Resource Limits

Edit docker-compose.yml to add limits:

services:
  palladiumd:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G

ElectrumX Performance

Increase concurrent indexing (in docker-compose.yml):

environment:
  INITIAL_CONCURRENT: "4"  # Default: 2

Notes

  • Data Persistence: All data stored in ./.palladium/, ./electrumx-data/, and ./certs/
  • Backup: Regularly backup .palladium/wallet.dat if you store funds
  • Network Switch: Always clear ElectrumX database when switching networks
  • Updates: Check for Palladium Core updates regularly

License

Distributed under the MIT license. See LICENSE file for details.

Support

Credits

Reference in New Issue View Git Blame Copy Permalink