mines/rin/miner/BUILD_GUIDE.md

RinHash Miner - Simple Build Guide

🚀 Quick Build Commands

Prerequisites

sudo apt update
sudo apt install build-essential autotools-dev autoconf pkg-config libcurl4-openssl-dev libjansson-dev libssl-dev libgmp-dev zlib1g-dev git automake libtool docker.io

🛠️ VS Code Integration (Recommended)

If you're using VS Code, the project now includes pre-configured tasks for easy building:

1. Open in VS Code:

   cd /mnt/shared/DEV/repos/d-popov.com/mines/rin/miner
   code .
   

2. Use Build Tasks:

   • Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
   • Type "Tasks: Run Task"
   • Select "Build Windows CPU Miner (Smart)" - RECOMMENDED
   • Or choose other build options as needed

Available VS Code Tasks:

• Build Windows CPU Miner (Smart) ⭐ - Automatically detects curl and builds optimally
• Build Windows CPU Miner (Original Curl) - Forces original curl implementation
• Build Windows CPU Miner (NO_CURL Fallback) - Direct socket fallback
• Clean Windows Build - Clean build artifacts
• Test Windows Executable - Verify build results

Benefits:

• ✅ No need to remember complex Docker commands
• ✅ Automatic curl detection and optimal build selection
• ✅ Integrated terminal output in VS Code
• ✅ One-click building from the IDE

🐳 Remote Docker Access Options

You don't need to SSH as root every time! Here are several ways to use Docker remotely from another machine:

Option 1: VS Code Docker Extension (Easiest - Recommended)

# On the build machine (where Docker is running) - Quick setup:
cd /mnt/shared/DEV/repos/d-popov.com/mines/rin/miner
./setup-remote-docker.sh

# Or manually:
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $USER  # Add user to docker group

In VS Code on your local machine:

1. Install "Docker" extension by Microsoft
2. Install "Remote-SSH" extension for SSH tunneling
3. Connect to build machine: Ctrl+Shift+P → "Remote-SSH: Connect to Host"
4. Use VS Code Docker extension to manage containers remotely

Option 2: Docker Remote API (Advanced)

# On the build machine - enable Docker API over TCP:
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/override.conf > /dev/null <<EOF
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

# Secure with TLS (recommended for production):
sudo dockerd --tlsverify --tlscacert=ca.pem --tlscert=server-cert.pem --tlskey=server-key.pem -H=0.0.0.0:2376

On your local machine:

# Set Docker context to remote host
docker context create remote-build --docker "host=tcp://BUILD_MACHINE_IP:2376"
docker context use remote-build

# Now all docker commands work remotely
docker ps
docker run --rm cpuminer-windows-builder echo "Hello from remote!"

Option 3: SSH Port Forwarding (Simple & Secure)

# On your local machine - forward Docker socket:
ssh -L localhost:2375:/var/run/docker.sock user@build-machine

# Or use SSH config (~/.ssh/config):
Host build-machine
    HostName your-build-machine-ip
    User your-username
    LocalForward 2375 /var/run/docker.sock

Then on your local machine:

# Set DOCKER_HOST environment variable
export DOCKER_HOST=tcp://localhost:2375

# All docker commands now work through SSH tunnel
docker ps
docker run --rm cpuminer-windows-builder echo "Remote build ready!"

Option 4: Docker Contexts (Clean Management)

# Create named context for your build machine
docker context create build-server --docker "host=ssh://user@build-machine"

# Switch between contexts easily
docker context use build-server
docker ps  # Shows containers on build machine

docker context use default  # Switch back to local
docker ps  # Shows local containers

Option 5: VS Code Dev Containers (Full Remote Development)

Create .devcontainer/devcontainer.json:

{
    "name": "RinHash Build Environment",
    "dockerFile": "Dockerfile",
    "context": "..",
    "remoteUser": "vscode",
    "mounts": [
        "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
    ],
    "extensions": [
        "ms-vscode.vscode-docker",
        "ms-vscode-remote.remote-ssh"
    ],
    "postCreateCommand": "sudo usermod -aG docker vscode"
}

Option 6: Docker Desktop Remote Connection (Windows 11)

For Windows 11 users with Docker Desktop:

Windows Setup:

1. Install Docker Desktop for Windows:

   • Download from: https://www.docker.com/products/docker-desktop
   • Enable WSL 2 integration during installation

2. Enable Docker Remote API:

   • Open Docker Desktop → Settings → General
   • Enable "Expose daemon on tcp://localhost:2375 without TLS"

3. Install OpenSSH Client:

   • Windows 11 has OpenSSH built-in
   • Enable in: Settings → Apps → Optional features → OpenSSH Client

Windows SSH Port Forwarding:

REM Command Prompt:
ssh -L localhost:2375:/var/run/docker.sock user@build-machine-ip

REM PowerShell:
ssh -L localhost:2375:/var/run/docker.sock user@build-machine-ip

Windows Environment Setup:

REM Command Prompt:
set DOCKER_HOST=tcp://localhost:2375

REM PowerShell:
$env:DOCKER_HOST = "tcp://localhost:2375"

Windows Docker Contexts:

REM Create context for remote Linux machine:
docker context create build-server --docker "host=ssh://user@build-machine-ip"

REM Switch to remote context:
docker context use build-server

REM Test remote connection:
docker run --rm cpuminer-windows-builder echo "Windows remote Docker working!"

🔒 Security Recommendations

For Production Use:

• ✅ Use SSH tunneling instead of exposing Docker API directly
• ✅ Enable Docker TLS verification
• ✅ Use VPN for additional security layer
• ✅ Limit Docker API access to specific IP ranges
• ✅ Regularly rotate SSH keys and certificates

Quick Start (Most Secure):

For Windows 11:

# On build machine - automated setup:
cd /mnt/shared/DEV/repos/d-popov.com/mines/rin/miner
./setup-remote-docker.sh

# On your Windows 11 machine - run setup script:
.\setup-remote-docker-windows.bat

# Or use PowerShell script:
.\setup-remote-docker-windows.ps1

For Linux/Mac:

# On build machine - automated setup:
cd /mnt/shared/DEV/repos/d-popov.com/mines/rin/miner
./setup-remote-docker.sh

# On your local machine:
ssh -L localhost:2375:/var/run/docker.sock user@build-machine
export DOCKER_HOST=tcp://localhost:2375
docker run --rm cpuminer-windows-builder echo "Ready for remote builds!"

📖 Detailed Instructions:

• Windows 11: See REMOTE_DOCKER_README.md for comprehensive setup guide
• All Platforms: Check BUILD_GUIDE.md for additional remote access options

1. Build GPU Library (ROCm/HIP)

cd /mnt/shared/DEV/repos/d-popov.com/mines/rin/miner/gpu/RinHash-hip

# Compile GPU kernel
/opt/rocm-6.4.3/bin/hipcc -c -O3 -fPIC rinhash.hip.cu -o build/rinhash.o

# Compile SHA3 component
/opt/rocm-6.4.3/bin/hipcc -c -O3 -fPIC sha3-256.hip.cu -o build/sha3-256.o

# Link shared library
/opt/rocm-6.4.3/bin/hipcc -shared -O3 build/rinhash.o build/sha3-256.o -o rocm-direct-output/gpu-libs/librinhash_hip.so -L/opt/rocm-6.4.3/lib -lamdhip64

# Install system-wide
sudo cp rocm-direct-output/gpu-libs/librinhash_hip.so /usr/local/lib/
sudo ldconfig

2. Build Windows CPU Miner (Docker Cross-Compilation) - RECOMMENDED

cd /mnt/shared/DEV/repos/d-popov.com/mines/rin/miner

# Build Windows executable with original curl implementation (recommended)
./build-windows-smart.sh

# Or use the manual command:
cd /home/db/Downloads/rinhash/cpuminer-opt-rin
sudo docker run --rm -v "$(pwd):/work" -v "$(pwd)/build/win:/output" cpuminer-windows-builder bash -c "cd /work && make clean && rm -rf Makefile Makefile.in configure config.* && ./autogen.sh && ./configure --host=x86_64-w64-mingw32 --with-curl=/usr/x86_64-w64-mingw32 CFLAGS='-O3 -march=x86-64 -DCURL_STATICLIB' LDFLAGS='-L/usr/x86_64-w64-mingw32/lib' LIBS='-lcurl -lbcrypt -ladvapi32 -lcrypt32 -lz -lws2_32 -pthread' && make -j4 && cp cpuminer.exe /output/cpuminer-curl.exe && cp /work/cpuminer.exe /output/"

# Verify build success
ls -la build/win/cpuminer*.exe

✅ SUCCESS: The smart build script now automatically:

• Detects curl availability in the Docker container
• Builds with original curl implementation (better performance)
• Falls back to NO_CURL only if curl linking fails
• Produces cpuminer-curl.exe (4.4MB) with full stratum features
• Also creates cpuminer-nocurl.exe (3.9MB) as fallback

Why Use Original Curl Implementation?

• Better Performance: Native curl library is optimized for networking
• Full Stratum Support: Complete stratum protocol implementation
• Stability: Less prone to connection drops and timeouts
• Compatibility: Works with all mining pools and proxies
• Security: Uses proven, battle-tested networking code

Build Output Comparison:

• cpuminer-curl.exe (4.4MB): Original implementation with full features
• cpuminer-nocurl.exe (3.9MB): Fallback with direct socket implementation

Recommendation: Always use cpuminer-curl.exe for production mining!

3. Alternative: Build Linux CPU Miner

cd /home/db/Downloads/rinhash/cpuminer-opt-rin

# Configure and build
./autogen.sh
./configure
make

# Or rebuild if already configured:
make clean && make

✅ Test Mining

CPU Only

./cpuminer -a rinhash -o stratum+tcp://192.168.0.188:3333 -u db.test -p x -t 4

GPU Accelerated

./cpuminer -a rinhashgpu -o stratum+tcp://192.168.0.188:3333 -u db.test -p x -t 4

📊 Expected Performance

Algorithm	Platform	Threads	Expected Hash Rate
rinhash (CPU)	Linux	4	~200-400 H/s
rinhash (CPU)	Windows	4	~180-360 H/s
rinhashgpu (GPU)	Linux	4	~800-1200 H/s
rinhashgpu (GPU)	Windows	4	~700-1000 H/s

🔧 Build Files

Linux

GPU Library: /usr/local/lib/librinhash_hip.so (252KB)
CPU Miner: ./cpuminer (executable)

Windows

CPU Miner: cpuminer.exe (executable)
GPU Library: librinhash_cuda.dll (if CUDA build)
Dependencies: Various .dll files (libcurl, jansson, etc.)

🚨 Troubleshooting

Linux Issues

• GPU not found: Check ROCm installation at /opt/rocm-6.4.3/
• Library missing: Run sudo ldconfig after installing
• Compilation errors: Install missing dependencies listed above
• Segmentation fault: Use simple algorithms without load control

Windows Issues

• MSYS2 issues: Use MinGW 64-bit terminal, not regular MSYS2
• CUDA not found: Install CUDA Toolkit and Visual Studio Build Tools
• Missing DLLs: Include required DLL files when distributing
• Performance: Windows may have 10-20% lower performance than Linux
• Build failures: Ensure Visual Studio Build Tools are installed for CUDA

🪟 Windows Build Instructions

Prerequisites for Windows

Option 1: Docker Desktop (Easiest - Recommended)

# Install Docker Desktop for Windows from https://www.docker.com/products/docker-desktop
# Make sure Docker Desktop is running

Option 2: MSYS2 (Advanced)

# Download and install MSYS2 from https://www.msys2.org/
# Open MSYS2 MinGW 64-bit terminal and run:

pacman -Syu
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make mingw-w64-x86_64-curl mingw-w64-x86_64-jansson mingw-w64-x86_64-openssl mingw-w64-x86_64-gmp mingw-w64-x86_64-zlib mingw-w64-x86_64-autotools mingw-w64-x86_64-pkg-config

Windows CPU Miner Build

Using Docker from Windows (Recommended)

# Open PowerShell or Command Prompt in Windows
cd C:\path\to\your\rinhash\cpuminer-opt-rin

# Build Windows executable using Docker (NO_CURL fallback for networking)
docker run --rm -v "${PWD}:/work" -v "${PWD}/build/win:/output" cpuminer-windows-builder bash -c "cd /work && make clean && rm -rf Makefile Makefile.in configure config.* && ./autogen.sh && ./configure --host=x86_64-w64-mingw32 CFLAGS='-O3 -march=x86-64 -DNO_CURL' LDFLAGS='-static' && make -j4 && cp cpuminer.exe /output/"

# Verify build success
dir build\win\cpuminer.exe

REM Alternative Windows Command Prompt version
cd C:\path\to\your\rinhash\cpuminer-opt-rin

docker run --rm -v "%CD%:/work" -v "%CD%/build/win:/output" cpuminer-windows-builder bash -c "cd /work && make clean && rm -rf Makefile Makefile.in configure config.* && ./autogen.sh && ./configure --host=x86_64-w64-mingw32 CFLAGS='-O3 -march=x86-64 -DNO_CURL' LDFLAGS='-static' && make -j4 && cp cpuminer.exe /output/"

dir build\win\cpuminer.exe

Using Docker from Linux Host

# Cross-compile for Windows
cd /home/db/Downloads/rinhash/cpuminer-opt-rin
sudo docker run --rm -v "$(pwd):/work" -v "$(pwd)/build/win:/output" cpuminer-windows-builder bash -c "cd /work && make clean && rm -rf Makefile Makefile.in configure config.* && ./autogen.sh && ./configure --host=x86_64-w64-mingw32 CFLAGS='-O3 -march=x86-64 -DNO_CURL' LDFLAGS='-static' && make -j4 && cp cpuminer.exe /output/"

Using MSYS2 (Advanced)

# Open MSYS2 MinGW 64-bit terminal
cd /c/path/to/mines/rin/miner/cpuminer-opt-rin

# Configure and build
./autogen.sh
./configure CFLAGS="-O3 -march=native -funroll-loops -fomit-frame-pointer"
make -j$(nproc)

Windows GPU Build Options

CUDA Build (NVIDIA GPUs)

# Prerequisites: Install CUDA Toolkit and Visual Studio
cd gpu/RinHash-cuda
build-cuda.bat

ROCm Build (AMD GPUs) - Limited Support

# Note: ROCm on Windows has limited support
# Consider using WSL2 with ROCm instead
cd gpu/RinHash-hip
# Use Linux build instructions in WSL2

Windows Testing

CPU Only (NO_CURL Direct Socket)

REM Navigate to build directory
cd C:\path\to\rinhash\cpuminer-opt-rin\build\win

REM Test CPU mining (direct socket connection, no curl dependency)
cpuminer.exe -a rinhash -o stratum+tcp://192.168.0.188:3333 -u db.test -p x -t 4

GPU Accelerated (if available)

REM Test GPU mining (requires GPU library)
cpuminer.exe -a rinhashgpu -o stratum+tcp://192.168.0.188:3333 -u db.test -p x -t 1

Production Mining (Zergpool Example)

REM Real mining pool example
cpuminer.exe -a rinhash -o stratum+tcp://rinhash.mine.zergpool.com:7148 -u bc1qjn4m6rmrveuxhk02a5qhe4r6kdcsvvt3vhdn9j -p c=BTC,mc=RIN,ID=StrixHalo -t 8

Debugging Network Issues

REM Enable verbose logging to debug connection issues
cpuminer.exe -a rinhash -o stratum+tcp://pool.example.com:3333 -u test -p x -t 1 -D

📝 Notes

• GPU implementation uses 4 blocks × 256 threads = 1024 GPU threads
• Automatic fallback to CPU if GPU library unavailable
• Thread count (-t) affects CPU threads, not GPU load directly
• Windows builds are primarily for CPU mining; GPU support is limited