mines/rin/miner/BUILD_GUIDE.md

# RinHash Miner - Simple Build Guide

## 🚀 Quick Build Commands

### Prerequisites
```bash
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
```

#### Git Credential Setup (Linux Users)
If VS Code keeps asking for Git credentials, set up credential management:

**Quick Setup (Linux Mint - Recommended):**
```bash
cd /mnt/shared/DEV/repos/d-popov.com/mines/rin/miner
./setup-git-credentials-linux.sh
```

**Test Your Setup:**
```bash
./test-git-credentials-linux.sh
```

**Available Methods:**
- ✅ **SSH Keys** - Most secure, no password prompts (recommended)
- ✅ **GNOME Keyring** - Encrypted storage using system keyring
- ✅ **Git Credential Cache** - Temporary credential caching
- ✅ **Personal Access Tokens** - For custom Git servers
- ✅ **VS Code Integration** - Built-in credential storage

**For git.d-popov.com (your custom server):**
1. **SSH Keys (Recommended):**
   - Run setup script and choose SSH option
   - Copy public key to git.d-popov.com
   - Test: `ssh -T git@git.d-popov.com`

2. **Personal Access Token:**
   - Generate token in git.d-popov.com web interface
   - Use username + token as password

3. **GNOME Keyring:**
   - Automatic encrypted storage
   - Integrated with system credentials

### 🛠️ 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:**
   ```bash
   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)
```bash
# 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)
```bash
# 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:**
```bash
# 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)
```bash
# 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:**
```bash
# 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)
```bash
# 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`:
```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: Remote Docker Access (Linux Mint)
**For Linux Mint users accessing remote Docker:**

#### Local Linux Setup:
1. **Install Docker locally (optional):**
   ```bash
   sudo apt update
   sudo apt install -y docker.io
   sudo systemctl enable docker
   sudo usermod -aG docker $USER
   # Logout and login again, or run: newgrp docker
   ```

2. **SSH Setup:**
   - SSH is built-in on Linux Mint
   - Generate SSH key if needed: `ssh-keygen -t ed25519`

#### SSH Port Forwarding:
```bash
# Forward Docker socket from remote machine
ssh -L localhost:2375:/var/run/docker.sock user@remote-build-machine

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

# Test remote connection
docker run --rm cpuminer-windows-builder echo "Remote Docker working!"
```

#### Docker Contexts:
```bash
# Create context for remote machine
docker context create build-server --docker "host=ssh://user@remote-build-machine"

# Switch to remote context
docker context use build-server

# All docker commands now work remotely
docker ps
docker run --rm cpuminer-windows-builder echo "Remote Docker working!"
```

#### VS Code Remote Development:
```bash
# Install VS Code extensions:
code --install-extension ms-vscode-remote.remote-ssh
code --install-extension ms-vscode.vscode-docker

# Connect to remote machine:
# Ctrl+Shift+P → "Remote-SSH: Connect to Host"
# Enter: ssh user@remote-build-machine

# Use Docker extension on remote machine
```

### 🔒 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 Linux Mint (Local Development):**
```bash
# On your Linux Mint machine - automated setup:
cd /mnt/shared/DEV/repos/d-popov.com/mines/rin/miner
./setup-remote-docker.sh

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

**For Remote Docker Access:**
```bash
# Create Docker context for remote machine:
docker context create build-server --docker "host=ssh://user@remote-build-machine"
docker context use build-server

# All Docker commands now work remotely:
docker run --rm cpuminer-windows-builder echo "Remote Docker working!"
```

📖 **Detailed Instructions:**
- **Linux Mint:** See [REMOTE_DOCKER_README.md](REMOTE_DOCKER_README.md) for comprehensive setup guide
- **All Platforms:** Check [BUILD_GUIDE.md](BUILD_GUIDE.md) for additional remote access options

### 1. Build GPU Library (ROCm/HIP)
```bash
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
```bash
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
```bash
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
```bash
./cpuminer -a rinhash -o stratum+tcp://192.168.0.188:3333 -u db.test -p x -t 4
```

### GPU Accelerated  
```bash
./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)
```bash
# Install Docker Desktop for Windows from https://www.docker.com/products/docker-desktop
# Make sure Docker Desktop is running
```

#### Option 2: MSYS2 (Advanced)
```bash
# 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)
```powershell
# 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
```

```cmd
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
```bash
# 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)
```bash
# 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)
```bash
# Prerequisites: Install CUDA Toolkit and Visual Studio
cd gpu/RinHash-cuda
build-cuda.bat
```

#### ROCm Build (AMD GPUs) - Limited Support
```bash
# 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)
```cmd
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)
```cmd
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)
```cmd
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
```cmd
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