mazacoin-explorer/INSTALL.md

Mazacoin Explorer - Installation Guide

Complete step-by-step instructions for deploying the Mazacoin blockchain explorer.

Table of Contents

1. Prerequisites
2. System Requirements
3. Mazacoin Node Setup
4. SSH Access Configuration
5. Explorer Deployment
6. DNS & Reverse Proxy Setup
7. Verification
8. Troubleshooting

---

Prerequisites

Required Services

• Mazacoin full node running with RPC enabled
• Docker 20.10+ and docker-compose 1.29+
• SSH access to the Mazacoin node (if remote)
• Domain name with DNS configured
• Reverse proxy (Caddy recommended) with TLS support

Network Access

• Mazacoin node must be accessible via SSH (if remote) or local network
• Port 8080 available for the explorer frontend
• Port 3000 available for the explorer backend API

---

System Requirements

Minimum Specs

• CPU: 2 cores
• RAM: 2 GB
• Disk: 10 GB free space
• Network: Stable internet connection

Recommended Specs

• CPU: 4+ cores
• RAM: 4+ GB
• Disk: 20+ GB SSD
• Network: 100+ Mbps

---

Mazacoin Node Setup

Option 1: Windows Node (GUI Wallet)

1. Download Mazacoin wallet from https://mazacoin.org/downloads

2. Install to desired location (e.g., E:\coins\MAZA)

3. Create RPC configuration file at E:\coins\MAZA\maza.conf:

   # RPC Settings
   server=1
   rpcuser=mazarpc
   rpcpassword=YOUR_SECURE_PASSWORD_HERE
   rpcallowip=127.0.0.1
   rpcport=12832
   
   # Optional: Enable transaction index (required for full address lookup)
   txindex=1
   

4. Start wallet with RPC enabled:

   E:\coins\MAZA\maza-qt.exe -server
   

5. Verify RPC works:

   E:\coins\MAZA\daemon\maza-cli.exe -datadir=E:\coins\MAZA getblockcount
   

Option 2: Linux Node (Daemon)

1. Install dependencies:

   sudo apt update
   sudo apt install build-essential libtool autotools-dev automake pkg-config \
     libssl-dev libevent-dev bsdmainutils libboost-all-dev
   

2. Download and compile Mazacoin:

   git clone https://github.com/MazaCoin/maza.git
   cd maza
   ./autogen.sh
   ./configure
   make
   sudo make install
   

3. Create config file at ~/.maza/maza.conf:

   server=1
   rpcuser=mazarpc
   rpcpassword=YOUR_SECURE_PASSWORD_HERE
   rpcallowip=127.0.0.1
   rpcport=12832
   txindex=1
   daemon=1
   

4. Start daemon:

   mazacoind
   

5. Verify:

   maza-cli getblockcount
   

---

SSH Access Configuration

If Mazacoin node is on a remote machine:

1. Generate SSH key pair on the explorer server:

   ssh-keygen -t ed25519 -f ~/.ssh/mazacoin_node -C "mazacoin-explorer"
   

2. Copy public key to node:

   ssh-copy-id -i ~/.ssh/mazacoin_node.pub user@node-ip
   

3. Test connection:

   ssh -i ~/.ssh/mazacoin_node user@node-ip "hostname"
   

4. Update backend configuration to use this key (see Explorer Deployment)

---

Explorer Deployment

Step 1: Clone Repository

git clone https://git.dashcaddy.net/sami/mazacoin-explorer.git
cd mazacoin-explorer

Step 2: Configure Backend

Edit backend/.env (create if it doesn't exist):

# Node Environment
NODE_ENV=production
PORT=3000

# Mazacoin Node Connection
MAZA_HOST=100.85.236.10
MAZA_USER=hello
MAZA_CLI_PATH=E:\\coins\\MAZA\\daemon\\maza-cli.exe
MAZA_DATADIR=E:\\coins\\MAZA
SSH_KEY_PATH=/root/.ssh/krystie_to_sami_pc

# API Configuration
CACHE_TTL=60
MAX_BLOCKS_PER_REQUEST=100
WEBSOCKET_POLL_INTERVAL=15000

Important Notes:

• Use double backslashes \\ for Windows paths in env files
• Adjust MAZA_HOST, MAZA_USER, SSH_KEY_PATH to match your setup
• If running node locally (not via SSH), set MAZA_HOST=localhost

Step 3: Configure Frontend

Edit frontend/.env:

# API URL (leave empty for same-origin, or specify full URL)
REACT_APP_API_URL=

# For development, use:
# REACT_APP_API_URL=http://localhost:3000

Step 4: Build and Start Services

# Build Docker images
docker-compose build

# Start containers in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

Step 5: Verify Services

# Check container status
docker-compose ps

# Test backend API
curl http://localhost:3000/api/health

# Expected response:
# {"status":"ok","blockHeight":4128056}

# Test frontend
curl http://localhost:8080

---

DNS & Reverse Proxy Setup

Option 1: Using DashCaddy (Automated)

If you have DashCaddy installed:

# Run the deployment script
./deploy.sh

This will:

• Create Caddy reverse proxy configuration
• Set up automatic Let's Encrypt TLS
• Configure DNS if using Technitium

Option 2: Manual Caddy Configuration

Create /etc/caddy/sites/maza.yourdomain.com:

maza.yourdomain.com {
    reverse_proxy localhost:8080
    
    # Optional: API sub-path
    handle /api/* {
        reverse_proxy localhost:3000
    }
    
    # TLS
    tls {
        protocols tls1.2 tls1.3
    }
    
    # Headers
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy no-referrer-when-downgrade
    }
    
    # Logging
    log {
        output file /var/log/caddy/maza.log
    }
}

Reload Caddy:

systemctl reload caddy

Option 3: Nginx Configuration

server {
    listen 80;
    server_name maza.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name maza.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /api/ {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # WebSocket support
    location /socket.io/ {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

---

Verification

1. Check All Services Running

# Docker containers
docker ps --filter name=mazacoin

# Expected output:
# mazacoin-backend   Up X minutes
# mazacoin-frontend  Up X minutes

2. Test API Endpoints

# Health check
curl https://maza.yourdomain.com/api/health

# Block count
curl https://maza.yourdomain.com/api/blockcount

# Latest blocks
curl https://maza.yourdomain.com/api/blocks/latest/5

# Network stats
curl https://maza.yourdomain.com/api/stats

3. Test Frontend

Visit https://maza.yourdomain.com in your browser and verify:

• ✅ Home page loads with latest blocks
• ✅ Search works (try searching a block number)
• ✅ Block detail page displays correctly
• ✅ Node map shows active nodes
• ✅ Network stats are populated

4. Test WebSocket

Open browser console on https://maza.yourdomain.com and check:

WebSocket connection to 'wss://maza.yourdomain.com/socket.io/' succeeded

---

Troubleshooting

Backend Won't Start

Issue: Error: connect ECONNREFUSED or SSH connection fails

Solutions:

1. Verify Mazacoin node is running:

   ssh -i ~/.ssh/mazacoin_node user@node-ip "tasklist | findstr maza"  # Windows
   ssh -i ~/.ssh/mazacoin_node user@node-ip "pgrep -f mazacoin"  # Linux
   

2. Test RPC manually:

   ssh -i ~/.ssh/mazacoin_node user@node-ip "maza-cli getblockcount"
   

3. Check backend logs:

   docker logs mazacoin-backend --tail 50
   

Frontend Shows "API Error"

Issue: Frontend can't reach backend API

Solutions:

1. Check backend is responding:

   curl http://localhost:3000/api/health
   

2. Verify environment variable REACT_APP_API_URL is correct in frontend

3. Check CORS settings in backend if accessing from different domain

4. Review frontend logs:

   docker logs mazacoin-frontend --tail 50
   

Node Map Not Showing Nodes

Issue: Map loads but shows 0 nodes

Solutions:

1. Check if Mazacoin node has active peer connections:

   curl http://localhost:3000/api/peers
   

2. Verify IP geolocation API is accessible (rate limits?)

3. Check browser console for JavaScript errors

4. Wait a few minutes for initial geolocation to complete

SSL Certificate Issues

Issue: "Your connection is not private" or certificate errors

Solutions:

1. Verify DNS is pointing to correct IP:

   dig maza.yourdomain.com
   

2. Check Caddy logs:

   journalctl -u caddy --no-pager -n 50
   

3. Manually request certificate:

   caddy reload --config /etc/caddy/Caddyfile
   

4. Ensure ports 80 and 443 are open:

   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   

High Memory Usage

Issue: Backend container using excessive RAM

Solutions:

1. Limit Docker container memory:

   # In docker-compose.yml
   services:
     backend:
       deploy:
         resources:
           limits:
             memory: 512M
   

2. Reduce cache size in backend config

3. Enable MongoDB for persistent caching instead of in-memory cache

Slow Block Queries

Issue: Block detail pages take >5 seconds to load

Solutions:

1. Check Mazacoin node responsiveness:

   time ssh user@node "maza-cli getblock BLOCKHASH"
   

2. Enable MongoDB caching (see backend README)

3. Reduce concurrent block fetches (edit backend/src/rpc/MazacoinRPC.js)

4. Consider running Mazacoin node on faster hardware

---

Performance Optimization

Enable Caching

MongoDB caching can significantly improve performance:

1. Start MongoDB container:

   docker run -d --name mongo \
     -p 27017:27017 \
     -v /data/mongo:/data/db \
     mongo:6
   

2. Update backend .env:

   MONGO_URI=mongodb://localhost:27017/mazacoin
   ENABLE_DB_CACHE=true
   

3. Restart backend:

   docker-compose restart backend
   

CDN Integration

For faster static asset delivery:

1. Use Cloudflare in front of your domain
2. Enable caching for /static/* paths
3. Configure browser caching headers in Caddy

---

Monitoring

Health Checks

Set up automated monitoring:

# Simple uptime check (add to cron)
*/5 * * * * curl -sf https://maza.yourdomain.com/api/health || echo "Explorer down!" | mail -s "Alert" admin@yourdomain.com

Prometheus Metrics (Optional)

The backend can export Prometheus metrics:

1. Enable in backend config
2. Add scrape target to Prometheus:

   scrape_configs:
     - job_name: 'mazacoin-explorer'
       static_configs:
         - targets: ['localhost:3000']
   

---

Updating

To update the explorer to a new version:

cd mazacoin-explorer

# Pull latest code
git pull origin main

# Rebuild images
docker-compose build

# Restart services (zero-downtime)
docker-compose up -d

# Check logs
docker-compose logs -f

---

Backup & Recovery

Backup Configuration

# Backup env files
cp backend/.env backend/.env.backup
cp frontend/.env frontend/.env.backup

# Backup Caddy config
sudo cp /etc/caddy/sites/maza.yourdomain.com /etc/caddy/sites/maza.yourdomain.com.backup

Database Backup (if using MongoDB)

docker exec mongo mongodump --out /backup

---

Support

For issues, questions, or contributions:

• Issues: https://git.dashcaddy.net/sami/mazacoin-explorer/issues
• Docs: See README.md and TROUBLESHOOTING.md
• Mazacoin Community: https://mazacoin.org

---

Installation complete! 🎉

Your Mazacoin blockchain explorer should now be running at your configured domain.