Snider/Mining
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Add MkDocs documentation site with GitHub Pages deployment

Browse source 
Convert documentation to MkDocs with Material theme for GitHub Pages hosting.
Includes comprehensive guides for API, CLI, desktop app, and development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
snider 2025-12-31 00:25:26 +00:00
parent e3122bb41e
commit 313782c161
20 changed files with 6019 additions and 166 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
.github/workflows/docs.yml vendored Normal file
View file

@ -0,0 +1,62 @@
name: Deploy MkDocs to GitHub Pages
on:
push:
branches:
- main
paths:
- 'docs/**'
- 'mkdocs.yml'
- '.github/workflows/docs.yml'
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
cache: 'pip'
- name: Install dependencies
run: |
pip install --upgrade pip
pip install -r docs/requirements.txt
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Build MkDocs site
run: mkdocs build --strict --verbose
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./site
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

4
.gitignore vendored
View file

@ -57,3 +57,7 @@ temp/
# goreleaser # goreleaser
.goreleaser.yaml.bak .goreleaser.yaml.bak
# MkDocs build output
/site/
.cache/

211
MKDOCS_SETUP.md Normal file
View file

@ -0,0 +1,211 @@
# MkDocs Setup Guide
This document provides a quick reference for the MkDocs documentation setup.
## Quick Start
```bash
# Install dependencies
pip install -r docs/requirements.txt
# Serve locally (with live reload)
mkdocs serve
# Build static site
mkdocs build
# Deploy to GitHub Pages
mkdocs gh-deploy
```
## Configuration Summary
### Location
- **Config file**: `mkdocs.yml`
- **Docs directory**: `docs/`
- **Build output**: `site/`
### Theme Settings
- **Theme**: Material for MkDocs
- **Default mode**: Dark mode (with toggle)
- **Primary color**: Deep Purple
- **Accent color**: Purple
- **Font**: Roboto / Roboto Mono
### Key Features Enabled
- Navigation tabs (sticky)
- Instant navigation with prefetch
- Search with suggestions
- Table of contents integration
- Code copy buttons
- Code annotations
- Edit/view page actions
- Git revision dates
### Plugins Configured
1. **search**: Enhanced search with smart separators
2. **git-revision-date-localized**: Shows page creation/modification dates
3. **minify**: Minifies HTML for production
4. **glightbox**: Image lightbox with zoom
### Markdown Extensions
- Admonitions (notes, warnings, tips)
- Code highlighting with line numbers
- Tabbed content blocks
- Task lists
- Mermaid diagrams
- Emojis
- Math equations (MathJax)
- Custom fences
- And more...
## Documentation Structure
```
docs/
├── index.md # Home page
├── getting-started/ # Installation, quickstart, config
├── cli/ # CLI command reference
├── api/ # API documentation
├── dashboard/ # Web dashboard docs
├── desktop/ # Desktop app docs
├── development/ # Development guides
├── architecture/ # Architecture docs
├── pools/ # Pool integration
├── miners/ # Miner-specific docs
├── troubleshooting/ # Troubleshooting guides
├── stylesheets/
│ └── extra.css # Custom styles
├── requirements.txt # Python dependencies
└── README.md # Docs contributor guide
```
## Deployment
### Automatic (GitHub Actions)
Documentation is automatically built and deployed to GitHub Pages on every push to `main` that modifies:
- `docs/**`
- `mkdocs.yml`
- `.github/workflows/docs.yml`
**Workflow**: `.github/workflows/docs.yml`
### Manual Deployment
```bash
# Build and deploy to gh-pages branch
mkdocs gh-deploy --force
```
## Viewing Documentation
### Local Development
- URL: `http://127.0.0.1:8000/`
- Command: `mkdocs serve`
### Production
- URL: `https://snider.github.io/Mining/`
- Branch: `gh-pages` (auto-generated)
## Adding New Pages
1. Create markdown file in appropriate directory:
```bash
# Example: Add new CLI command documentation
touch docs/cli/benchmark.md
```
2. Add to navigation in `mkdocs.yml`:
```yaml
nav:
- CLI Reference:
- benchmark: cli/benchmark.md
```
3. Test locally:
```bash
mkdocs serve
```
4. Commit and push (auto-deploys)
## Markdown Features
### Code Blocks with Highlighting
````markdown
```go title="main.go" linenums="1" hl_lines="2 3"
package main
import "fmt"
func main() {
fmt.Println("Hello!")
}
```
````
### Admonitions
```markdown
!!! note "Note Title"
This is a note admonition.
!!! warning "Warning"
This is a warning.
!!! tip "Pro Tip"
This is a helpful tip.
```
### Tabbed Content
```markdown
=== "Linux"
```bash
./miner-ctrl serve
```
=== "Windows"
```powershell
miner-ctrl.exe serve
```
```
### Mermaid Diagrams
````markdown
```mermaid
graph LR
A[Start] --> B{Check}
B -->|Yes| C[OK]
B -->|No| D[Error]
```
````
## Troubleshooting
### Site not building?
```bash
# Check for errors
mkdocs build --strict --verbose
```
### Missing dependencies?
```bash
# Reinstall all dependencies
pip install -r docs/requirements.txt --force-reinstall
```
### Navigation not showing up?
- Check YAML syntax in `mkdocs.yml` nav section
- Ensure markdown files exist at specified paths
- Verify indentation (use spaces, not tabs)
### Changes not appearing locally?
- MkDocs has live reload, but try:
- Hard refresh browser (Ctrl+Shift+R)
- Restart `mkdocs serve`
- Clear browser cache
## Resources
- [MkDocs Documentation](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/)
- [Mermaid Diagrams](https://mermaid-js.github.io/mermaid/)

247
README.md
View file

@ -7,162 +7,173 @@
[![Release](https://img.shields.io/github/release/Snider/Mining.svg)](https://github.com/Snider/Mining/releases) [![Release](https://img.shields.io/github/release/Snider/Mining.svg)](https://github.com/Snider/Mining/releases)
[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](https://opensource.org/license/eupl-1-2) [![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](https://opensource.org/license/eupl-1-2)
GoLang Miner management with embedable RESTful control - A modern, modular package for managing cryptocurrency miners. A modern, modular cryptocurrency mining management platform with GPU support, RESTful API, and cross-platform desktop application.
```bash <img width="834" height="657" alt="Mining Dashboard" src="https://github.com/user-attachments/assets/d4fc4704-819c-4aca-bcd3-ae4af6e25c1b" />
miner-ctrl serve --host localhost --port 9090 --namespace /api/v1/mining
```
```html
<script type="module" src="./mbe-mining-dashboard.js"></script>
<mde-mining-dashboard miner-name="xmrig" wallet="..." pool="..." api-base-url="http://localhost:9090/api/v1/mining"></mde-mining-dashboard>
```
<img width="834" height="657" alt="image" src="https://github.com/user-attachments/assets/d4fc4704-819c-4aca-bcd3-ae4af6e25c1b" />
## Overview
Mining is a Go package designed to provide comprehensive miner management capabilities. It can be used both as a standalone CLI tool and as a module/plugin in other Go projects. The package offers:
- **Miner Lifecycle Management**: Start, stop, and monitor miners
- **Status Tracking**: Real-time status and hash rate monitoring
- **CLI Interface**: Easy-to-use command-line interface built with Cobra
- **Modular Design**: Import as a package in your own projects
- **RESTful Ready**: Designed for integration with RESTful control systems
## Features ## Features
- ✅ Start and stop miners programmatically ### Supported Algorithms
- ✅ Monitor miner status and performance
- ✅ Track hash rates
- ✅ List all active miners
- ✅ CLI for easy management
- ✅ Designed as a reusable Go module
- ✅ Comprehensive test coverage
- ✅ Standards-compliant configuration (CodeRabbit, GoReleaser)
## Installation | Algorithm | Coin | CPU | GPU (OpenCL) | GPU (CUDA) |
|-----------|------|-----|--------------|------------|
| RandomX | Monero (XMR) | ✅ | ✅ | ✅ |
| KawPow | Ravencoin (RVN) | ❌ | ✅ | ✅ |
| ETChash | Ethereum Classic (ETC) | ❌ | ✅ | ✅ |
| ProgPowZ | Zano (ZANO) | ❌ | ✅ | ✅ |
| Blake3 | Decred (DCR) | ✅ | ✅ | ✅ |
| CryptoNight | Various | ✅ | ✅ | ✅ |
### As a CLI Tool ### Core Capabilities
- **Multi-Algorithm Mining**: Support for CPU and GPU mining across multiple algorithms
- **Dual Mining**: Run CPU and GPU mining simultaneously with separate pools
- **Profile Management**: Save and switch between mining configurations
- **Real-time Monitoring**: Live hashrate, shares, and performance metrics
- **RESTful API**: Full control via HTTP endpoints with Swagger documentation
- **Web Dashboard**: Embeddable Angular web component for any application
- **Desktop Application**: Native cross-platform app built with Wails v3
- **Mobile Responsive**: Touch-friendly UI with drawer navigation
### Mining Software
Manages installation and configuration of:
- **XMRig** - High-performance CPU/GPU miner (RandomX, CryptoNight)
- **T-Rex** - NVIDIA GPU miner (KawPow, Ethash, and more)
- **lolMiner** - AMD/NVIDIA GPU miner (Ethash, Beam, Equihash)
- **TT-Miner** - NVIDIA GPU miner (Ethash, KawPow, Autolykos2)
## Quick Start
### CLI
```bash ```bash
# Install
go install github.com/Snider/Mining/cmd/mining@latest go install github.com/Snider/Mining/cmd/mining@latest
# Start the API server
miner-ctrl serve --host localhost --port 9090
# Or use the interactive shell
miner-ctrl serve
``` ```
### As a Go Module ### Web Component
```html
<script type="module" src="./mbe-mining-dashboard.js"></script>
<snider-mining api-base-url="http://localhost:9090/api/v1/mining"></snider-mining>
```
### Desktop Application
Download pre-built binaries from [Releases](https://github.com/Snider/Mining/releases) or build from source:
```bash ```bash
go get github.com/Snider/Mining cd cmd/desktop/mining-desktop
wails3 build
``` ```
## Usage ## Architecture
### CLI Commands
The `miner-ctrl` provides the following commands:
``` ```
miner-ctrl completion Generate the autocompletion script for the specified shell Mining/
miner-ctrl doctor Check and refresh the status of installed miners ├── cmd/
miner-ctrl help Help about any command │ ├── mining/ # CLI application
miner-ctrl install Install or update a miner │ └── desktop/ # Wails desktop app
miner-ctrl list List running and available miners ├── pkg/mining/ # Core Go package
miner-ctrl serve Start the mining service and interactive shell │ ├── mining.go # Interfaces and types
miner-ctrl start Start a new miner │ ├── manager.go # Miner lifecycle management
miner-ctrl status Get status of a running miner │ ├── service.go # RESTful API (Gin)
miner-ctrl stop Stop a running miner │ ├── xmrig.go # XMRig implementation
miner-ctrl uninstall Uninstall a miner │ └── profile_manager.go # Profile persistence
miner-ctrl update Check for updates to installed miners ├── miner/core/ # Modified XMRig with algorithm support
│ └── src/
│ ├── backend/opencl/ # OpenCL GPU kernels
│ ├── backend/cuda/ # CUDA GPU kernels
│ └── crypto/ # Algorithm implementations
└── ui/ # Angular 20+ web dashboard
└── src/app/
├── components/ # Reusable UI components
└── pages/ # Route pages
``` ```
For more details on any command, use `miner-ctrl [command] --help`. ## API Reference
### RESTful API Endpoints Base path: `/api/v1/mining`
When running the `miner-ctrl serve` command, the following RESTful API endpoints are exposed (default base path `/api/v1/mining`): | Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/info` | System info and installed miners |
| GET | `/miners` | List running miners |
| POST | `/miners/:name` | Start a miner |
| DELETE | `/miners/:name` | Stop a miner |
| GET | `/miners/:name/stats` | Get miner statistics |
| GET | `/profiles` | List saved profiles |
| POST | `/profiles` | Create a profile |
| PUT | `/profiles/:id` | Update a profile |
| DELETE | `/profiles/:id` | Delete a profile |
| POST | `/miners/:name/install` | Install miner software |
- `GET /api/v1/mining/info` - Get cached miner installation information and system details. Swagger UI: `http://localhost:9090/api/v1/mining/swagger/index.html`
- `POST /api/v1/mining/doctor` - Perform a live check on all available miners to verify their installation status, version, and path.
- `POST /api/v1/mining/update` - Check if any installed miners have a new version available for download.
- `GET /api/v1/mining/miners` - Get a list of all running miners.
- `GET /api/v1/mining/miners/available` - Get a list of all available miners.
- `POST /api/v1/mining/miners/:miner_name` - Start a new miner with the given configuration.
- `POST /api/v1/mining/miners/:miner_name/install` - Install a new miner or update an existing one.
- `DELETE /api/v1/mining/miners/:miner_name/uninstall` - Remove all files for a specific miner.
- `DELETE /api/v1/mining/miners/:miner_name` - Stop a running miner by its name.
- `GET /api/v1/mining/miners/:miner_name/stats` - Get statistics for a running miner.
- `GET /api/v1/mining/swagger/*any` - Serve Swagger UI for API documentation.
Swagger documentation is typically available at `http://<host>:<port>/api/v1/mining/swagger/index.html`.
## Development ## Development
### Prerequisites ### Prerequisites
- Go 1.24 or higher - Go 1.24+
- Make (optional, for using Makefile targets) - Node.js 20+ (for UI development)
- CMake 3.21+ (for miner core)
- OpenCL SDK (for GPU support)
### Build ### Build Commands
```bash ```bash
# Build the CLI # Backend
go build -o miner-ctrl ./cmd/mining make build # Build CLI binary
make test # Run tests with coverage
make dev # Start dev server on :9090
# Run tests # Frontend
go test ./... cd ui
npm install
npm run build # Build web component
npm test # Run unit tests (36 specs)
# Run tests with coverage # Desktop
go test -cover ./... cd cmd/desktop/mining-desktop
``` wails3 build # Build native app
### Project Structure # Miner Core (GPU support)
cd miner/core
``` mkdir build && cd build
. cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
├── cmd/ make -j$(nproc)
│ └── mining/ # CLI application
│ ├── main.go # CLI entry point
│ └── cmd/ # Cobra commands
├── pkg/
│ └── mining/ # Core mining package
│ ├── mining.go # Main package code
│ └── mining_test.go
├── main.go # Demo/development main
├── .coderabbit.yaml # CodeRabbit configuration
├── .goreleaser.yaml # GoReleaser configuration
├── .gitignore
├── go.mod
├── LICENSE
└── README.md
``` ```
## Configuration ## Configuration
### CodeRabbit Mining profiles are stored in `~/.config/lethean-desktop/mining_profiles.json`
The project uses CodeRabbit for automated code reviews. Configuration is in `.coderabbit.yaml`. Example profile:
```json
### GoReleaser {
"id": "uuid",
Releases are managed with GoReleaser. Configuration is in `.goreleaser.yaml`. To create a release: "name": "My XMR Mining",
"minerType": "xmrig",
```bash "config": {
# Tag a version "pool": "stratum+tcp://pool.supportxmr.com:3333",
git tag -a v0.1.0 -m "Release v0.1.0" "wallet": "YOUR_WALLET_ADDRESS",
git push origin v0.1.0 "algo": "rx/0"
}
# GoReleaser will automatically build and publish }
``` ```
## Contributing ## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository 1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`) 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`) 3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`) 4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request 5. Open a Pull Request
@ -172,10 +183,8 @@ This project is licensed under the EUPL-1.2 License - see the [LICENSE](LICENSE)
## Acknowledgments ## Acknowledgments
- Built with [Cobra](https://github.com/spf13/cobra) for CLI functionality - [XMRig](https://github.com/xmrig/xmrig) - High performance miner
- Configured for [CodeRabbit](https://coderabbit.ai) automated reviews - [Wails](https://wails.io) - Desktop application framework
- Releases managed with [GoReleaser](https://goreleaser.com) - [Angular](https://angular.io) - Web framework
- [Gin](https://gin-gonic.com) - HTTP web framework
## Support - [Cobra](https://github.com/spf13/cobra) - CLI framework
For issues, questions, or contributions, please open an issue on GitHub.

135
docs/README.md
View file

@ -2,13 +2,142 @@
Welcome to the documentation for the Mining project. This folder contains detailed information about the API, CLI, architecture, and development processes. Welcome to the documentation for the Mining project. This folder contains detailed information about the API, CLI, architecture, and development processes.
## Documentation Index ## GitHub Pages Documentation
The full documentation is built with [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, and is available at:
**https://snider.github.io/Mining/**
## Local Development
### Prerequisites
- Python 3.x
- pip
### Setup & Serve
1. Install dependencies:
```bash
pip install -r docs/requirements.txt
```
2. Serve the documentation locally:
```bash
mkdocs serve
```
The documentation will be available at `http://127.0.0.1:8000/`
### Building
To build the static site:
```bash
mkdocs build
```
The built site will be in the `site/` directory.
## Legacy Documentation
- [**API Documentation**](API.md): Detailed information about the RESTful API endpoints, request/response formats, and Swagger usage. - [**API Documentation**](API.md): Detailed information about the RESTful API endpoints, request/response formats, and Swagger usage.
- [**CLI Documentation**](CLI.md): A comprehensive guide to the Command Line Interface, including command descriptions and usage examples. - [**CLI Documentation**](CLI.md): A comprehensive guide to the Command Line Interface, including command descriptions and usage examples.
- [**Architecture Guide**](ARCHITECTURE.md): An overview of the project's design, including the modular `ManagerInterface`, core packages, and data flow. - [**Architecture Guide**](ARCHITECTURE.md): An overview of the project's design, including the modular `ManagerInterface`, core packages, and data flow.
- [**Development Guide**](DEVELOPMENT.md): Instructions for contributors on how to build, test, and release the project. - [**Development Guide**](DEVELOPMENT.md): Instructions for contributors on how to build, test, and release the project.
## Quick Start ## Project Structure
For a quick start guide, please refer to the main [README.md](../README.md) in the project root. ```
docs/
├── index.md # Home page
├── getting-started/ # Getting started guides
├── cli/ # CLI command reference
├── api/ # API documentation
├── dashboard/ # Web dashboard docs
├── desktop/ # Desktop application docs
├── development/ # Development guides
├── architecture/ # Architecture documentation
├── pools/ # Pool integration docs
├── miners/ # Miner-specific documentation
├── troubleshooting/ # Troubleshooting guides
├── stylesheets/
│ └── extra.css # Custom CSS
└── requirements.txt # Python dependencies
```
## Writing Documentation
### Markdown Extensions
This project uses PyMdown Extensions which provide additional features:
- **Admonitions**: `!!! note`, `!!! warning`, `!!! tip`, etc.
- **Code blocks**: Syntax highlighting with line numbers
- **Tabs**: Tabbed content blocks
- **Task lists**: GitHub-style checkboxes
- **Emojis**: `:smile:`
- **Mermaid diagrams**: Flow charts and diagrams
### Example Admonition
```markdown
!!! tip "Mining Tip"
Make sure to check your GPU temperature regularly!
```
### Example Code Block
````markdown
```go title="main.go" linenums="1" hl_lines="2 3"
package main
import "fmt"
func main() {
fmt.Println("Hello, Mining!")
}
```
````
### Example Tabbed Content
```markdown
=== "Linux"
```bash
./miner-ctrl serve
```
=== "Windows"
```powershell
miner-ctrl.exe serve
```
=== "macOS"
```bash
./miner-ctrl serve
```
```
## Contributing
When adding new documentation:
1. Create markdown files in the appropriate directory
2. Add the new page to the `nav:` section in `mkdocs.yml`
3. Follow the existing style and structure
4. Test locally with `mkdocs serve`
5. Submit a pull request
## Deployment
Documentation is automatically deployed to GitHub Pages when changes are pushed to the `main` branch. The deployment is handled by the `.github/workflows/docs.yml` workflow.
## Resources
- [MkDocs Documentation](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/)
- [Mermaid Diagrams](https://mermaid-js.github.io/mermaid/)

712
docs/api/endpoints.md Normal file
View file

@ -0,0 +1,712 @@
# API Endpoints
Complete reference for all Mining Platform API endpoints.
## System Endpoints
### GET /info
Retrieve system information and installed miners.
**Response:**
```json
{
"success": true,
"data": {
"os": "linux",
"arch": "amd64",
"goVersion": "go1.24.0",
"totalMemory": 16777216,
"installedMiners": [
{
"type": "xmrig",
"version": "6.21.0",
"installed": true,
"path": "/home/user/.local/share/lethean-desktop/miners/xmrig"
}
]
}
}
```
**Example:**
```bash
curl http://localhost:8080/api/v1/mining/info
```
### POST /doctor
Perform a live diagnostic check on all miners and system configuration.
**Response:**
```json
{
"success": true,
"data": {
"miners": [
{
"type": "xmrig",
"installed": true,
"version": "6.21.0",
"status": "ok",
"issues": []
}
],
"gpu": {
"opencl": {
"available": true,
"devices": [
{
"id": 0,
"name": "NVIDIA GeForce RTX 3080",
"memory": 10737418240
}
]
},
"cuda": {
"available": true,
"version": "12.0",
"devices": [
{
"id": 0,
"name": "NVIDIA GeForce RTX 3080",
"computeCapability": "8.6"
}
]
}
},
"recommendations": [
"System configured correctly",
"All miners up to date"
]
}
}
```
**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/mining/doctor
```
### POST /update
Check for updates to installed miners.
**Query Parameters:**
- `check_only` (bool): Only check, don't install updates
- `all` (bool): Update all miners
**Response:**
```json
{
"success": true,
"data": {
"updates": [
{
"miner": "xmrig",
"currentVersion": "6.21.0",
"latestVersion": "6.21.1",
"updateAvailable": true
}
]
}
}
```
**Example:**
```bash
# Check for updates
curl -X POST "http://localhost:8080/api/v1/mining/update?check_only=true"
# Update all
curl -X POST "http://localhost:8080/api/v1/mining/update?all=true"
```
## Miner Management
### GET /miners
List all currently running miners.
**Query Parameters:**
- `status` (string): Filter by status (running, stopped, error)
- `type` (string): Filter by miner type
**Response:**
```json
{
"success": true,
"data": [
{
"name": "xmrig",
"type": "xmrig",
"status": "running",
"pid": 12345,
"startedAt": "2025-12-31T10:00:00Z",
"config": {
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_WALLET_ADDRESS",
"algo": "rx/0"
}
}
]
}
```
**Example:**
```bash
# List all miners
curl http://localhost:8080/api/v1/mining/miners
# Filter by status
curl "http://localhost:8080/api/v1/mining/miners?status=running"
```
### GET /miners/available
List all available miner types that can be installed.
**Response:**
```json
{
"success": true,
"data": [
{
"type": "xmrig",
"name": "XMRig",
"description": "High-performance CPU/GPU miner for RandomX and CryptoNight algorithms",
"algorithms": ["rx/0", "rx/wow", "cn/r", "cn/0"],
"cpuSupport": true,
"gpuSupport": true,
"latestVersion": "6.21.1",
"installed": true,
"installedVersion": "6.21.0"
}
]
}
```
**Example:**
```bash
curl http://localhost:8080/api/v1/mining/miners/available
```
### POST /miners/:miner_type
Start a new miner instance.
**Path Parameters:**
- `miner_type`: Type of miner to start (e.g., `xmrig`)
**Request Body:**
```json
{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_WALLET_ADDRESS",
"algo": "rx/0",
"threads": 4,
"cpuPriority": 3,
"cuda": {
"enabled": false,
"devices": []
},
"opencl": {
"enabled": false,
"devices": []
}
}
```
**Response:**
```json
{
"success": true,
"data": {
"name": "xmrig",
"type": "xmrig",
"status": "starting",
"pid": 12345,
"message": "Miner started successfully"
}
}
```
**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/mining/miners/xmrig \
-H "Content-Type: application/json" \
-d '{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_WALLET_ADDRESS",
"algo": "rx/0",
"threads": 4
}'
```
### DELETE /miners/:miner_name
Stop a running miner instance.
**Path Parameters:**
- `miner_name`: Name of the miner to stop
**Response:**
```json
{
"success": true,
"data": {
"message": "Miner stopped successfully",
"name": "xmrig",
"stoppedAt": "2025-12-31T12:00:00Z"
}
}
```
**Example:**
```bash
curl -X DELETE http://localhost:8080/api/v1/mining/miners/xmrig
```
### POST /miners/:miner_type/install
Install or update a specific miner.
**Path Parameters:**
- `miner_type`: Type of miner to install
**Query Parameters:**
- `force` (bool): Force reinstall even if already installed
- `version` (string): Install specific version
**Response:**
```json
{
"success": true,
"data": {
"miner": "xmrig",
"version": "6.21.1",
"path": "/home/user/.local/share/lethean-desktop/miners/xmrig",
"message": "Miner installed successfully"
}
}
```
**Example:**
```bash
# Install latest version
curl -X POST http://localhost:8080/api/v1/mining/miners/xmrig/install
# Install specific version
curl -X POST "http://localhost:8080/api/v1/mining/miners/xmrig/install?version=6.21.0"
# Force reinstall
curl -X POST "http://localhost:8080/api/v1/mining/miners/xmrig/install?force=true"
```
### DELETE /miners/:miner_type/uninstall
Uninstall a miner and remove its files.
**Path Parameters:**
- `miner_type`: Type of miner to uninstall
**Response:**
```json
{
"success": true,
"data": {
"message": "Miner uninstalled successfully",
"miner": "xmrig"
}
}
```
**Example:**
```bash
curl -X DELETE http://localhost:8080/api/v1/mining/miners/xmrig/uninstall
```
### GET /miners/:miner_name/stats
Get real-time statistics for a running miner.
**Path Parameters:**
- `miner_name`: Name of the running miner
**Response:**
```json
{
"success": true,
"data": {
"hashrate": 4520.5,
"hashrateAvg": 4485.2,
"shares": {
"accepted": 42,
"rejected": 0,
"invalid": 0
},
"uptime": 8215,
"connection": {
"pool": "pool.supportxmr.com:3333",
"uptime": 8215,
"ping": 45,
"failures": 0
},
"cpu": {
"usage": 95.5,
"temperature": 65.2
}
}
}
```
**Example:**
```bash
curl http://localhost:8080/api/v1/mining/miners/xmrig/stats
```
### GET /miners/:miner_name/hashrate-history
Get historical hashrate data for a miner.
**Path Parameters:**
- `miner_name`: Name of the miner
**Query Parameters:**
- `resolution` (string): Data resolution (`10s`, `1m`, `5m`, `1h`)
- `duration` (string): Time duration (`5m`, `1h`, `24h`)
**Response:**
```json
{
"success": true,
"data": {
"points": [
{
"timestamp": "2025-12-31T12:00:00Z",
"hashrate": 4520.5
},
{
"timestamp": "2025-12-31T12:00:10Z",
"hashrate": 4535.2
}
],
"resolution": "10s",
"duration": "5m"
}
}
```
**Example:**
```bash
# Get last 5 minutes at 10s resolution
curl "http://localhost:8080/api/v1/mining/miners/xmrig/hashrate-history?resolution=10s&duration=5m"
# Get last 24 hours at 1m resolution
curl "http://localhost:8080/api/v1/mining/miners/xmrig/hashrate-history?resolution=1m&duration=24h"
```
## Profile Management
### GET /profiles
List all saved mining profiles.
**Query Parameters:**
- `miner_type` (string): Filter by miner type
**Response:**
```json
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "XMR - SupportXMR",
"description": "Monero mining on SupportXMR pool",
"minerType": "xmrig",
"config": {
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_WALLET_ADDRESS",
"algo": "rx/0"
},
"createdAt": "2025-12-31T10:00:00Z",
"updatedAt": "2025-12-31T12:00:00Z"
}
]
}
```
**Example:**
```bash
curl http://localhost:8080/api/v1/mining/profiles
```
### GET /profiles/:id
Get a specific mining profile by ID.
**Path Parameters:**
- `id`: Profile UUID
**Response:**
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "XMR - SupportXMR",
"minerType": "xmrig",
"config": { /* ... */ }
}
}
```
**Example:**
```bash
curl http://localhost:8080/api/v1/mining/profiles/550e8400-e29b-41d4-a716-446655440000
```
### POST /profiles
Create a new mining profile.
**Request Body:**
```json
{
"name": "XMR - SupportXMR",
"description": "Monero mining on SupportXMR pool",
"minerType": "xmrig",
"config": {
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_WALLET_ADDRESS",
"algo": "rx/0",
"threads": 4
}
}
```
**Response:**
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "XMR - SupportXMR",
"message": "Profile created successfully"
}
}
```
**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/mining/profiles \
-H "Content-Type: application/json" \
-d '{
"name": "XMR - SupportXMR",
"minerType": "xmrig",
"config": {
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_WALLET_ADDRESS",
"algo": "rx/0"
}
}'
```
### PUT /profiles/:id
Update an existing mining profile.
**Path Parameters:**
- `id`: Profile UUID
**Request Body:** Same as POST /profiles
**Response:**
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"message": "Profile updated successfully"
}
}
```
**Example:**
```bash
curl -X PUT http://localhost:8080/api/v1/mining/profiles/550e8400-e29b-41d4-a716-446655440000 \
-H "Content-Type: application/json" \
-d '{
"name": "XMR - Updated",
"config": { /* ... */ }
}'
```
### DELETE /profiles/:id
Delete a mining profile.
**Path Parameters:**
- `id`: Profile UUID
**Response:**
```json
{
"success": true,
"data": {
"message": "Profile deleted successfully",
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
**Example:**
```bash
curl -X DELETE http://localhost:8080/api/v1/mining/profiles/550e8400-e29b-41d4-a716-446655440000
```
### POST /profiles/:id/start
Start mining using a saved profile.
**Path Parameters:**
- `id`: Profile UUID
**Response:**
```json
{
"success": true,
"data": {
"minerName": "xmrig",
"profile": "XMR - SupportXMR",
"status": "starting"
}
}
```
**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/mining/profiles/550e8400-e29b-41d4-a716-446655440000/start
```
## Error Responses
All error responses follow this format:
```json
{
"success": false,
"error": {
"code": "MINER_NOT_FOUND",
"message": "Miner 'xmrig' is not currently running",
"details": {
"minerName": "xmrig",
"suggestion": "Start the miner first using POST /miners/xmrig"
}
}
}
```
Common error scenarios:
### 400 Bad Request
```json
{
"success": false,
"error": {
"code": "INVALID_CONFIG",
"message": "Invalid configuration provided",
"details": {
"field": "wallet",
"issue": "Wallet address must be 95 characters"
}
}
}
```
### 404 Not Found
```json
{
"success": false,
"error": {
"code": "MINER_NOT_FOUND",
"message": "Miner 'xmrig' not found"
}
}
```
### 409 Conflict
```json
{
"success": false,
"error": {
"code": "MINER_ALREADY_RUNNING",
"message": "Miner 'xmrig' is already running",
"details": {
"pid": 12345,
"startedAt": "2025-12-31T10:00:00Z"
}
}
}
```
### 500 Internal Server Error
```json
{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred",
"details": {
"requestId": "req_123456"
}
}
}
```
## Next Steps
- Try the [Swagger UI](http://localhost:8080/api/v1/mining/swagger/index.html) for interactive testing
- See [API Overview](index.md) for authentication and general information
- Check the [Development Guide](../development/index.md) for contributing

417
docs/api/index.md Normal file
View file

@ -0,0 +1,417 @@
# API Overview
The Mining Platform provides a comprehensive RESTful API for managing cryptocurrency miners programmatically.
## Base URL
All API endpoints are prefixed with the configured namespace (default: `/api/v1/mining`):
```
http://localhost:8080/api/v1/mining
```
You can customize the namespace when starting the server:
```bash
miner-ctrl serve --namespace /custom/path
```
## Swagger Documentation
Interactive API documentation is available via Swagger UI when the server is running:
```
http://localhost:8080/api/v1/mining/swagger/index.html
```
The Swagger specification is also available in multiple formats:
- **JSON**: `/docs/swagger.json`
- **YAML**: `/docs/swagger.yaml`
## Authentication
Currently, the API does not require authentication. This is suitable for local/trusted networks.
For production deployments, consider:
- Running behind a reverse proxy with authentication
- Implementing API key authentication
- Using OAuth2/JWT for multi-user scenarios
## API Versioning
The API follows semantic versioning:
- **Current Version**: v1
- **Endpoint Format**: `/api/v{version}/mining/{endpoint}`
- **Backward Compatibility**: Maintained within major versions
## Content Type
All requests and responses use JSON:
```
Content-Type: application/json
```
## Response Format
All API responses follow a consistent structure:
### Success Response
```json
{
"success": true,
"data": {
// Response data here
}
}
```
### Error Response
```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {
// Additional error context
}
}
}
```
## HTTP Status Codes
The API uses standard HTTP status codes:
| Code | Meaning | Usage |
|------|---------|-------|
| 200 | OK | Request successful |
| 201 | Created | Resource created successfully |
| 204 | No Content | Request successful, no content to return |
| 400 | Bad Request | Invalid request parameters |
| 404 | Not Found | Resource not found |
| 409 | Conflict | Resource already exists or conflicting state |
| 500 | Internal Server Error | Server-side error |
| 503 | Service Unavailable | Service temporarily unavailable |
## Rate Limiting
Currently, there is no rate limiting implemented. For production use, consider:
- Implementing rate limits at the reverse proxy level
- Using nginx `limit_req` module
- Implementing application-level rate limiting
## CORS
Cross-Origin Resource Sharing (CORS) is enabled by default for all origins. To restrict:
```bash
# Start server with CORS restrictions (future feature)
miner-ctrl serve --cors-origin "https://example.com"
```
## WebSocket Support
Real-time updates are available via WebSocket connection:
```
ws://localhost:8080/api/v1/mining/ws
```
The WebSocket provides:
- Real-time miner statistics
- Live hashrate updates
- Event notifications (miner start/stop/crash)
Example JavaScript client:
```javascript
const ws = new WebSocket('ws://localhost:8080/api/v1/mining/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Update:', data);
};
```
## Pagination
List endpoints support pagination via query parameters:
```
GET /api/v1/mining/miners?page=1&limit=10
```
Response includes pagination metadata:
```json
{
"success": true,
"data": {
"items": [ /* ... */ ],
"pagination": {
"page": 1,
"limit": 10,
"total": 42,
"pages": 5
}
}
}
```
## Filtering and Sorting
List endpoints support filtering and sorting:
```
GET /api/v1/mining/miners?status=running&sort=hashrate&order=desc
```
Common parameters:
- `status`: Filter by status (running, stopped, error)
- `type`: Filter by miner type (xmrig, etc.)
- `sort`: Sort field (name, hashrate, uptime)
- `order`: Sort order (asc, desc)
## Date and Time Format
All timestamps use ISO 8601 format with UTC timezone:
```
2025-12-31T23:59:59Z
```
## Field Naming
API fields use camelCase naming:
```json
{
"minerName": "xmrig",
"hashRate": 4520,
"acceptedShares": 42
}
```
## Data Models
### SystemInfo
System information and installed miners.
```json
{
"os": "linux",
"arch": "amd64",
"goVersion": "go1.24.0",
"totalMemory": 16777216,
"installedMiners": [
{
"type": "xmrig",
"version": "6.21.0",
"installed": true,
"path": "/home/user/.local/share/lethean-desktop/miners/xmrig"
}
]
}
```
### Config
Miner configuration object.
```json
{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_WALLET_ADDRESS",
"algo": "rx/0",
"threads": 4,
"cpuPriority": 3,
"cuda": {
"enabled": false,
"devices": []
},
"opencl": {
"enabled": false,
"devices": []
}
}
```
### PerformanceMetrics
Real-time miner statistics.
```json
{
"hashrate": 4520.5,
"hashrateAvg": 4485.2,
"shares": {
"accepted": 42,
"rejected": 0,
"invalid": 0
},
"uptime": 8215,
"connection": {
"pool": "pool.supportxmr.com:3333",
"uptime": 8215,
"ping": 45,
"failures": 0
},
"cpu": {
"usage": 95.5,
"temperature": 65.2
},
"gpu": [
{
"id": 0,
"name": "NVIDIA GeForce RTX 3080",
"hashrate": 95234.5,
"temperature": 68.5,
"fanSpeed": 75,
"powerUsage": 220
}
]
}
```
### HashratePoint
Historical hashrate data point.
```json
{
"timestamp": "2025-12-31T12:00:00Z",
"hashrate": 4520.5,
"resolution": "10s"
}
```
### MiningProfile
Saved mining configuration.
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "XMR - SupportXMR",
"description": "Monero mining on SupportXMR pool",
"minerType": "xmrig",
"config": { /* Config object */ },
"createdAt": "2025-12-31T10:00:00Z",
"updatedAt": "2025-12-31T12:00:00Z"
}
```
## Error Codes
Common error codes returned by the API:
| Code | Description |
|------|-------------|
| `MINER_NOT_FOUND` | Specified miner not found |
| `MINER_ALREADY_RUNNING` | Miner is already running |
| `MINER_NOT_INSTALLED` | Miner software not installed |
| `INVALID_CONFIG` | Invalid configuration provided |
| `POOL_UNREACHABLE` | Cannot connect to mining pool |
| `PROFILE_NOT_FOUND` | Mining profile not found |
| `PROFILE_ALREADY_EXISTS` | Profile with same name exists |
| `INVALID_WALLET` | Invalid wallet address format |
| `INSUFFICIENT_RESOURCES` | System resources insufficient |
## Examples
See the [Endpoints](endpoints.md) page for detailed examples of each API endpoint.
## Client Libraries
### JavaScript/TypeScript
```javascript
const BASE_URL = 'http://localhost:8080/api/v1/mining';
async function startMiner(config) {
const response = await fetch(`${BASE_URL}/miners/xmrig`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(config)
});
return response.json();
}
async function getMiners() {
const response = await fetch(`${BASE_URL}/miners`);
return response.json();
}
```
### Python
```python
import requests
BASE_URL = 'http://localhost:8080/api/v1/mining'
def start_miner(config):
response = requests.post(
f'{BASE_URL}/miners/xmrig',
json=config
)
return response.json()
def get_miners():
response = requests.get(f'{BASE_URL}/miners')
return response.json()
```
### Go
```go
import (
"bytes"
"encoding/json"
"net/http"
)
const baseURL = "http://localhost:8080/api/v1/mining"
func startMiner(config map[string]interface{}) error {
data, _ := json.Marshal(config)
resp, err := http.Post(
baseURL+"/miners/xmrig",
"application/json",
bytes.NewBuffer(data),
)
if err != nil {
return err
}
defer resp.Body.Close()
return nil
}
```
### cURL
```bash
# Start miner
curl -X POST http://localhost:8080/api/v1/mining/miners/xmrig \
-H "Content-Type: application/json" \
-d '{"pool":"stratum+tcp://pool.supportxmr.com:3333","wallet":"YOUR_WALLET","algo":"rx/0"}'
# Get miners
curl http://localhost:8080/api/v1/mining/miners
# Get stats
curl http://localhost:8080/api/v1/mining/miners/xmrig/stats
```
## Next Steps
- Browse the [API Endpoints](endpoints.md) for detailed documentation
- Try the interactive [Swagger UI](http://localhost:8080/api/v1/mining/swagger/index.html)
- See the [Development Guide](../development/index.md) for contributing

615
docs/development/architecture.md Normal file
View file

@ -0,0 +1,615 @@
# Architecture
This document provides a detailed overview of the Mining Platform architecture, design decisions, and component interactions.
## High-Level Architecture
The Mining Platform follows a modular, layered architecture:
```
┌─────────────────────────────────────────────────────────┐
│ User Interfaces │
│ ┌──────────┐ ┌───────────────┐ ┌─────────────────┐ │
│ │ CLI │ │ Web Dashboard │ │ Desktop App │ │
│ │ (Cobra) │ │ (Angular) │ │ (Wails+Angular)│ │
│ └────┬─────┘ └───────┬───────┘ └────────┬────────┘ │
└───────┼────────────────┼───────────────────┼───────────┘
│ │ │
└────────────────┼───────────────────┘
│
┌────────────────────────┼───────────────────────────────┐
│ REST API Layer (Gin) │
│ /api/v1/mining/* │
└────────────────────────┬───────────────────────────────┘
│
┌────────────────────────┼───────────────────────────────┐
│ Core Business Logic (pkg/mining) │
│ ┌──────────────┐ ┌─────────────┐ ┌───────────────┐ │
│ │ Manager │ │ Miner │ │ Profile │ │
│ │ Interface │ │ Implemen- │ │ Manager │ │
│ │ │ │ tations │ │ │ │
│ └──────┬───────┘ └──────┬──────┘ └───────┬───────┘ │
└─────────┼──────────────────┼─────────────────┼─────────┘
│ │ │
┌─────────┼──────────────────┼─────────────────┼─────────┐
│ System Layer (OS, Filesystem, Processes) │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Mining Software (XMRig, T-Rex, lolMiner, etc.) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## Core Components
### Manager Interface
The `ManagerInterface` is the central abstraction for miner lifecycle management.
**Location:** `pkg/mining/manager.go`
**Purpose:**
- Provides a contract for miner operations
- Enables testing through mocking
- Supports multiple miner implementations
- Manages running miners in-memory
**Interface Definition:**
```go
type ManagerInterface interface {
StartMiner(minerType string, config *Config) (Miner, error)
StopMiner(name string) error
GetMiner(name string) (Miner, error)
ListMiners() []Miner
ListAvailableMiners() []AvailableMiner
GetMinerHashrateHistory(name string) ([]HashratePoint, error)
Stop()
}
```
**Implementation Details:**
- Maintains a `map[string]Miner` for running miners
- Automatically collects statistics every 10 seconds
- Supports autostart from configuration
- Thread-safe with mutex locks
### Miner Interface
The `Miner` interface defines the contract for all miner implementations.
**Location:** `pkg/mining/mining.go`
**Interface Definition:**
```go
type Miner interface {
GetName() string
GetStats() (*PerformanceMetrics, error)
Stop() error
IsRunning() bool
GetConfig() *Config
GetHashrateHistory() []HashratePoint
}
```
**Implementations:**
- **XMRigMiner**: CPU/GPU mining for RandomX and CryptoNight
- **TRexMiner**: NVIDIA GPU mining for KawPow, Ethash (future)
- **LolMiner**: AMD/NVIDIA mining for Ethash, Beam (future)
### BaseMiner
Provides shared functionality for all miner implementations.
**Location:** `pkg/mining/miner.go`
**Features:**
- Binary discovery and installation
- Archive extraction (tar.gz, tar.xz, zip)
- Download from URLs with progress tracking
- Hashrate history management
- XDG directory compliance
**Key Methods:**
```go
func (m *BaseMiner) InstallFromURL(url string) error
func (m *BaseMiner) FindBinary(name string) (string, error)
func (m *BaseMiner) AddHashratePoint(hashrate float64)
func (m *BaseMiner) GetHashrateHistory() []HashratePoint
```
**Hashrate History:**
- High-resolution: 10-second intervals, 5-minute retention
- Low-resolution: 1-minute averages, 24-hour retention
- Automatically manages data retention
### XMRig Implementation
Complete implementation for XMRig miner.
**Files:**
- `pkg/mining/xmrig.go`: Core implementation
- `pkg/mining/xmrig_start.go`: Startup logic
- `pkg/mining/xmrig_stats.go`: Statistics parsing
**Architecture:**
```
┌─────────────────────────────────────────────┐
│ XMRigMiner │
│ ┌─────────────────────────────────────┐ │
│ │ BaseMiner (embedded) │ │
│ │ - Binary management │ │
│ │ - Hashrate history │ │
│ └─────────────────────────────────────┘ │
│ │
│ Start() → Generate config.json │
│ → Execute xmrig binary │
│ → Capture stdout/stderr │
│ → Monitor process │
│ │
│ GetStats() → Poll HTTP API │
│ → Parse JSON response │
│ → Return PerformanceMetrics │
│ │
│ Stop() → Send SIGTERM │
│ → Wait for graceful shutdown │
│ → Force kill if needed │
└─────────────────────────────────────────────┘
```
**Configuration Generation:**
- Creates JSON config file
- Supports CPU and GPU mining
- Handles pool authentication
- Manages algorithm selection
- Configures API endpoint for stats
**Statistics Collection:**
- Polls XMRig HTTP API (default: `http://127.0.0.1:44321/1/summary`)
- Parses JSON response
- Extracts hashrate, shares, connection info
- Updates hashrate history
### Service Layer (REST API)
Exposes the Manager functionality via HTTP endpoints.
**Location:** `pkg/mining/service.go`
**Framework:** Gin Web Framework
**Features:**
- RESTful API design
- Swagger documentation
- CORS support
- JSON request/response
- Error handling middleware
- Route grouping
**Route Organization:**
```
/api/v1/mining
├── /info # GET - System info
├── /doctor # POST - Diagnostics
├── /update # POST - Check updates
├── /miners
│ ├── / # GET - List miners
│ ├── /available # GET - Available types
│ ├── /:miner_type # POST - Start miner
│ ├── /:miner_name # DELETE - Stop miner
│ ├── /:miner_name/stats # GET - Get statistics
│ ├── /:miner_type/install # POST - Install miner
│ └── /:miner_type/uninstall # DELETE - Uninstall
└── /profiles
├── / # GET - List profiles
├── / # POST - Create profile
├── /:id # GET - Get profile
├── /:id # PUT - Update profile
├── /:id # DELETE - Delete profile
└── /:id/start # POST - Start from profile
```
**Middleware Stack:**
1. Logger
2. Recovery (panic handler)
3. CORS
4. Request validation
5. Response formatter
### Profile Manager
Manages saved mining configurations.
**Location:** `pkg/mining/profile_manager.go`
**Storage:** JSON file at `~/.config/lethean-desktop/mining_profiles.json`
**Data Structure:**
```go
type MiningProfile struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
MinerType string `json:"minerType"`
Config *Config `json:"config"`
CreatedAt time.Time `json:"createdAt"`
UpdatedAt time.Time `json:"updatedAt"`
}
```
**Features:**
- CRUD operations for profiles
- UUID-based profile IDs
- Atomic file writes
- Import/export support
- Validation
### Config Manager
Handles autostart and last-used configurations.
**Location:** `pkg/mining/config_manager.go`
**Storage:** JSON file at `~/.config/lethean-desktop/mining_config.json`
**Features:**
- Autostart configuration
- Last-used miner configs
- Preference storage
- Default settings
## Data Flow
### Starting a Miner
```
User Request
│
├─→ CLI: miner-ctrl start xmrig --config config.json
├─→ API: POST /api/v1/mining/miners/xmrig
└─→ Desktop: profileManager.start(profileId)
│
▼
Service Layer (service.go)
│
├─→ Validate request
├─→ Parse configuration
└─→ Call manager.StartMiner()
│
▼
Manager (manager.go)
│
├─→ Check if miner already running
├─→ Validate configuration
└─→ Create miner instance
│
▼
Miner Implementation (xmrig.go)
│
├─→ Generate config.json
├─→ Find/verify binary
├─→ Execute miner process
├─→ Capture output streams
└─→ Start statistics collection
│
▼
Manager
│
├─→ Store miner in running map
└─→ Return miner instance
│
▼
Service Layer
│
├─→ Format response
└─→ Return HTTP 200/201
```
### Collecting Statistics
```
Background goroutine (every 10s)
│
▼
For each running miner:
│
├─→ miner.GetStats()
│ │
│ ├─→ Poll HTTP API
│ ├─→ Parse JSON
│ └─→ Return PerformanceMetrics
│
├─→ Extract hashrate
└─→ miner.AddHashratePoint(hashrate)
│
├─→ Store in high-res buffer
├─→ Update low-res averages
└─→ Prune old data
```
### Retrieving Statistics (API Request)
```
Client: GET /api/v1/mining/miners/xmrig/stats
│
▼
Service Layer
│
├─→ Extract miner name
└─→ Call manager.GetMiner(name)
│
▼
Manager
│
├─→ Lookup in miners map
└─→ Return miner instance
│
▼
Service Layer
│
├─→ Call miner.GetStats()
├─→ Format response
└─→ Return JSON
```
## Frontend Architecture (Angular)
### Component Hierarchy
```
AppComponent
├── DashboardPage
│ ├── MinerStatusCard
│ ├── HashrateCard
│ ├── SharesCard
│ └── EarningsCard
├── MinersPage
│ ├── RunningMinersList
│ │ └── MinerCard
│ └── AvailableMinersList
│ └── MinerInstallCard
├── ProfilesPage
│ ├── ProfileList
│ │ └── ProfileCard
│ └── ProfileEditor
├── StatisticsPage
│ ├── HashrateChart
│ ├── SharesChart
│ └── TimeRangeSelector
├── PoolsPage
│ ├── RecommendedPools
│ └── CustomPoolForm
├── AdminPage
│ ├── SystemInfo
│ ├── MinerManagement
│ └── DiagnosticsPanel
└── SettingsPage
├── GeneralSettings
├── NotificationSettings
└── AdvancedSettings
```
### Services
**MinerService**
- API communication
- Miner lifecycle management
- Statistics fetching
**ProfileService**
- Profile CRUD operations
- Profile storage
- Import/export
**WebSocketService**
- Real-time updates
- Event notifications
- Connection management
**ThemeService**
- Theme switching
- Preference persistence
### State Management
The application uses RxJS for state management:
- Services emit observables
- Components subscribe to updates
- Automatic cleanup on destroy
- Centralized error handling
## Desktop Application (Wails)
### Architecture
```
┌─────────────────────────────────────────┐
│ Go Backend (main.go) │
│ ┌───────────────────────────────────┐ │
│ │ MiningService │ │
│ │ - Wraps pkg/mining.Manager │ │
│ │ - Exposes methods to frontend │ │
│ └────────────┬──────────────────────┘ │
└───────────────┼─────────────────────────┘
│ Wails Bindings
┌───────────────┼─────────────────────────┐
│ TypeScript Frontend │
│ ┌────────────┴──────────────────────┐ │
│ │ Angular Application │ │
│ │ (Embedded from ui/dist/browser) │ │
│ └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
**MiningService** (`miningservice.go`):
- Binds Go methods to frontend
- Handles lifecycle events
- Manages application state
- Provides system tray integration
**Auto-generated Bindings** (`frontend/bindings/`):
- TypeScript definitions
- Type-safe Go method calls
- Event system integration
## Modified XMRig Core
### OpenCL Backend
**Location:** `miner/core/src/backend/opencl/`
**Supported Algorithms:**
- ETChash (Ethereum Classic)
- ProgPowZ (Zano)
- KawPow (Ravencoin)
**Key Files:**
- `cl/etchash/`: OpenCL kernels for ETChash
- `cl/progpowz/`: OpenCL kernels for ProgPowZ
- `runners/OclEtchashRunner.*`: ETChash GPU runner
- `runners/OclProgPowZRunner.*`: ProgPowZ GPU runner
### Algorithm Implementations
**Location:** `miner/core/src/crypto/`
**ETChash:**
- `ETCCache.cpp/h`: DAG cache management
- Ethash variant optimized for ETC
**ProgPowZ:**
- Custom ProgPow variant for Zano
- Period-based algorithm rotation
### Build System
CMake-based build with conditional compilation:
```cmake
option(WITH_OPENCL "Enable OpenCL backend" ON)
option(WITH_CUDA "Enable CUDA backend" ON)
```
Automatically detects:
- OpenCL SDK
- CUDA Toolkit
- GPU capabilities
## Security Considerations
### API Security
- No authentication by default (local use)
- Consider reverse proxy for production
- CORS enabled for web component
- Input validation on all endpoints
### File System
- XDG Base Directory compliance
- Restricted file permissions (0644 for config, 0755 for binaries)
- Atomic file writes for configs
- Safe path handling (no path traversal)
### Process Management
- Graceful shutdown (SIGTERM → SIGKILL)
- Process isolation
- Resource limits (if configured)
- Log rotation
## Performance Optimizations
### Hashrate History
- Two-tier storage (high-res + low-res)
- Automatic data pruning
- In-memory ring buffers
- Minimal memory footprint
### Statistics Collection
- Background goroutine (non-blocking)
- Cached HTTP requests
- JSON parsing optimization
- Error resilience
### Frontend
- Lazy loading of routes
- Virtual scrolling for large lists
- Chart data decimation
- Debounced API calls
## Extensibility
### Adding New Miners
1. Implement `Miner` interface
2. Extend `BaseMiner` for common functionality
3. Register in `Manager`
4. Add API endpoints if needed
### Adding New Algorithms
1. Add algorithm support to miner core
2. Update configuration structs
3. Add validation rules
4. Update UI selectors
### Adding New Frontends
The REST API is frontend-agnostic:
- Mobile apps (React Native, Flutter)
- CLI tools
- Third-party integrations
- Monitoring dashboards
## Deployment Patterns
### Single User (Local)
```
User Machine
├── miner-ctrl (CLI/API server)
├── Browser (accessing localhost:8080)
└── Mining software (XMRig, etc.)
```
### Multi-User (Server)
```
Server
├── miner-ctrl (API server on 0.0.0.0:8080)
└── Mining software
Reverse Proxy (nginx)
├── HTTPS termination
├── Authentication
└── Rate limiting
Clients
├── Web browsers
├── Mobile apps
└── API clients
```
### Desktop (Standalone)
```
Single Binary (Wails)
├── Embedded API server
├── Embedded frontend
└── Integrated mining software
```
## Next Steps
- Review [Development Guide](index.md) for setup instructions
- Read [Contributing Guidelines](contributing.md) for contribution process
- See [API Documentation](../api/index.md) for endpoint details

451
docs/development/contributing.md Normal file
View file

@ -0,0 +1,451 @@
# Contributing Guidelines
Thank you for considering contributing to the Mining Platform! This document provides guidelines for contributing to the project.
## Code of Conduct
We expect all contributors to:
- Be respectful and inclusive
- Welcome newcomers and help them get started
- Accept constructive criticism gracefully
- Focus on what is best for the community
- Show empathy towards other community members
## How to Contribute
### Reporting Bugs
Before creating a bug report:
1. Check the [existing issues](https://github.com/Snider/Mining/issues) to avoid duplicates
2. Collect relevant information (OS, Go version, logs, etc.)
3. Create a minimal reproducible example if possible
When creating a bug report, include:
- **Title**: Clear, descriptive summary
- **Description**: Detailed explanation of the issue
- **Steps to Reproduce**: Numbered list of steps
- **Expected Behavior**: What should happen
- **Actual Behavior**: What actually happens
- **Environment**:
- OS and version
- Go version
- Mining Platform version
- Miner software versions
- **Logs**: Relevant log output or error messages
- **Screenshots**: If applicable
**Example:**
```markdown
### Bug: XMRig miner fails to start on Ubuntu 22.04
**Description:**
When attempting to start XMRig through the API, the miner process starts but immediately exits with code 1.
**Steps to Reproduce:**
1. Install Mining Platform v1.0.0
2. Install XMRig via `miner-ctrl install xmrig`
3. Start miner with: `POST /api/v1/mining/miners/xmrig`
4. Check miner status
**Expected Behavior:**
Miner should start and begin mining.
**Actual Behavior:**
Miner process exits immediately with error code 1.
**Environment:**
- OS: Ubuntu 22.04 LTS
- Go: 1.24.0
- Mining Platform: v1.0.0
- XMRig: 6.21.0
**Logs:**
```
[ERROR] Failed to start miner: process exited with code 1
[DEBUG] XMRig output: FAILED TO ALLOCATE MEMORY
```
```
### Requesting Features
Feature requests are welcome! Before submitting:
1. Check if the feature already exists or is planned
2. Search existing feature requests
3. Consider if it fits the project scope
When requesting a feature, include:
- **Use Case**: Why is this feature needed?
- **Description**: What should the feature do?
- **Alternatives**: Have you considered other solutions?
- **Examples**: How would it work?
### Submitting Pull Requests
1. **Fork the Repository**
```bash
git clone https://github.com/YOUR_USERNAME/Mining.git
cd Mining
git remote add upstream https://github.com/Snider/Mining.git
```
2. **Create a Branch**
```bash
git checkout -b feature/my-feature
```
Branch naming convention:
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation changes
- `refactor/` - Code refactoring
- `test/` - Test improvements
3. **Make Your Changes**
- Write clean, readable code
- Follow existing code style
- Add tests for new functionality
- Update documentation
- Keep commits focused and atomic
4. **Test Your Changes**
```bash
# Run Go tests
make test
make lint
# Run frontend tests
cd ui && npm test
cd ui && npm run e2e
```
5. **Commit Your Changes**
Follow [Conventional Commits](https://www.conventionalcommits.org/):
```
type(scope): description
[optional body]
[optional footer]
```
**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `style`: Formatting
- `refactor`: Code restructuring
- `test`: Tests
- `chore`: Maintenance
**Examples:**
```bash
git commit -m "feat(api): Add profile management endpoints"
git commit -m "fix(miner): Fix XMRig hashrate calculation"
git commit -m "docs(readme): Update installation instructions"
```
6. **Push to Your Fork**
```bash
git push origin feature/my-feature
```
7. **Create a Pull Request**
- Go to the GitHub repository
- Click "New Pull Request"
- Select your branch
- Fill in the PR template
- Link related issues
### Pull Request Guidelines
A good pull request:
- **Focused**: Addresses a single concern
- **Tested**: Includes tests for new code
- **Documented**: Updates relevant documentation
- **Reviewed**: Self-reviewed before submission
- **Linked**: References related issues
**PR Template:**
```markdown
## Description
Brief description of what this PR does.
## Related Issues
Fixes #123
Relates to #456
## Changes
- Added X functionality
- Fixed Y bug
- Updated Z documentation
## Testing
- [ ] Go tests pass
- [ ] Frontend tests pass
- [ ] E2E tests pass
- [ ] Manual testing completed
## Checklist
- [ ] Code follows project style
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Changelog updated
- [ ] Commits are atomic and well-described
```
## Development Setup
See the [Development Guide](index.md) for detailed setup instructions.
Quick start:
```bash
# Clone
git clone https://github.com/YOUR_USERNAME/Mining.git
cd Mining
# Install dependencies
go mod download
cd ui && npm install
# Run tests
make test
cd ui && npm test
# Start dev environment
make dev
```
## Coding Standards
### Go Code Style
- Follow [Effective Go](https://golang.org/doc/effective_go)
- Use `gofmt` for formatting
- Run `golangci-lint` before committing
- Write descriptive variable and function names
- Add comments for exported symbols
- Keep functions small and focused
- Handle errors explicitly
**Good Example:**
```go
// GetMinerStats retrieves real-time statistics from a running miner.
// Returns an error if the miner is not running or stats cannot be fetched.
func (m *Manager) GetMinerStats(name string) (*PerformanceMetrics, error) {
m.mu.RLock()
miner, exists := m.miners[name]
m.mu.RUnlock()
if !exists {
return nil, fmt.Errorf("miner %s not found", name)
}
stats, err := miner.GetStats()
if err != nil {
return nil, fmt.Errorf("failed to get stats: %w", err)
}
return stats, nil
}
```
### TypeScript/Angular Code Style
- Follow [Angular Style Guide](https://angular.io/guide/styleguide)
- Use TypeScript strict mode
- Prefer interfaces over types for objects
- Use RxJS operators properly
- Clean up subscriptions in `ngOnDestroy`
- Write unit tests for components and services
**Good Example:**
```typescript
@Component({
selector: 'app-miner-card',
standalone: true,
imports: [CommonModule],
templateUrl: './miner-card.component.html',
styleUrls: ['./miner-card.component.scss']
})
export class MinerCardComponent implements OnInit, OnDestroy {
@Input() minerId!: string;
miner$!: Observable<Miner>;
private destroy$ = new Subject<void>();
constructor(private minerService: MinerService) {}
ngOnInit(): void {
this.miner$ = this.minerService.getMiner(this.minerId).pipe(
takeUntil(this.destroy$)
);
}
ngOnDestroy(): void {
this.destroy$.next();
this.destroy$.complete();
}
}
```
### Documentation Standards
- Document all public APIs
- Include examples in documentation
- Keep documentation up-to-date with code
- Use clear, concise language
- Add diagrams for complex concepts
## Testing Requirements
### Required Tests
All PRs must include appropriate tests:
**Go:**
- Unit tests for new functions
- Integration tests for complex flows
- Table-driven tests where applicable
- Error case coverage
**TypeScript/Angular:**
- Unit tests for components and services
- E2E tests for user flows
- Test edge cases and error states
### Running Tests
```bash
# Go tests
make test # All tests
go test -v ./pkg/mining/... # Specific package
go test -run TestName # Specific test
# Frontend tests
cd ui
npm test # Unit tests
npm run test:coverage # With coverage
npm run e2e # E2E tests
```
### Test Coverage
- Aim for >80% coverage for new code
- Don't decrease overall coverage
- Focus on critical paths
Check coverage:
```bash
make coverage # Opens HTML report
```
## Documentation
### API Documentation
API changes require Swagger annotation updates:
```go
// @Summary Get miner statistics
// @Description Returns real-time performance metrics for a running miner
// @Tags miners
// @Accept json
// @Produce json
// @Param name path string true "Miner name"
// @Success 200 {object} PerformanceMetrics
// @Failure 404 {object} ErrorResponse
// @Router /miners/{name}/stats [get]
func (s *Service) handleGetStats(c *gin.Context) {
// Implementation
}
```
Generate docs:
```bash
make docs
```
### User Documentation
Update relevant docs in `docs/`:
- Getting started guides
- API references
- User guides
- Architecture docs
## Review Process
### What to Expect
1. **Automated Checks**: CI runs tests and linters
2. **Code Review**: Maintainers review your code
3. **Feedback**: You may be asked to make changes
4. **Approval**: Once approved, PR will be merged
### Responding to Feedback
- Be open to suggestions
- Ask questions if unclear
- Make requested changes promptly
- Explain your reasoning when necessary
- Keep discussions professional and constructive
## Release Process
Releases are handled by maintainers:
1. Update `CHANGELOG.md`
2. Create a version tag
3. GitHub Actions builds and releases
Contributors don't need to worry about releases unless they're maintainers.
## Getting Help
If you need help:
- **Documentation**: Check the `docs/` folder first
- **Issues**: Search existing issues
- **Discussions**: Use GitHub Discussions for questions
- **Discord**: Join our community server (if available)
## Recognition
Contributors are recognized in:
- `CONTRIBUTORS.md` file
- Release notes
- GitHub contributors page
Thank you for contributing to Mining Platform!
## Quick Links
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Development Guide](index.md)
- [Architecture Guide](architecture.md)
- [API Documentation](../api/index.md)
- [Issue Tracker](https://github.com/Snider/Mining/issues)
- [Discussions](https://github.com/Snider/Mining/discussions)

570
docs/development/index.md Normal file
View file

@ -0,0 +1,570 @@
# Development Guide
Welcome to the Mining Platform development guide. This documentation will help you set up your development environment and contribute to the project.
## Prerequisites
### Required Tools
- **Go**: Version 1.24 or higher
- **Node.js**: Version 20 or higher (for UI development)
- **npm**: Version 10 or higher
- **Make**: For build automation
- **Git**: For version control
### Optional Tools
- **CMake**: Version 3.21+ (for building miner core with GPU support)
- **OpenCL SDK**: For AMD GPU development
- **CUDA Toolkit**: For NVIDIA GPU development
- **golangci-lint**: For code linting
- **swag**: For generating Swagger documentation
### Install Development Tools
**Go Tools:**
```bash
# Install swag for Swagger generation
go install github.com/swaggo/swag/cmd/swag@latest
# Install golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```
**Node.js Tools:**
```bash
cd ui
npm install
```
## Getting the Source Code
Clone the repository:
```bash
git clone https://github.com/Snider/Mining.git
cd Mining
```
## Project Structure
```
Mining/
├── cmd/
│ ├── mining/ # CLI application
│ │ ├── main.go # Entry point
│ │ └── cmd/ # Cobra commands
│ └── desktop/ # Desktop application
│ └── mining-desktop/ # Wails app
├── pkg/mining/ # Core Go package
│ ├── mining.go # Interfaces and types
│ ├── manager.go # Miner lifecycle management
│ ├── service.go # REST API (Gin)
│ ├── xmrig.go # XMRig implementation
│ ├── xmrig_start.go # XMRig startup logic
│ ├── xmrig_stats.go # XMRig statistics parsing
│ ├── profile_manager.go # Profile persistence
│ └── config_manager.go # Config management
├── miner/core/ # Modified XMRig
│ └── src/
│ ├── backend/ # Mining backends
│ │ ├── opencl/ # OpenCL (AMD/NVIDIA)
│ │ └── cuda/ # CUDA (NVIDIA)
│ └── crypto/ # Algorithm implementations
│ ├── etchash/ # Ethereum Classic
│ └── progpowz/ # Zano
├── ui/ # Angular web dashboard
│ ├── src/
│ │ ├── app/
│ │ │ ├── components/ # Reusable components
│ │ │ ├── pages/ # Route pages
│ │ │ └── services/ # API services
│ │ └── environments/ # Environment configs
│ ├── e2e/ # Playwright E2E tests
│ └── package.json
├── docs/ # Documentation
├── Makefile # Build automation
└── README.md
```
## Building the Project
### Backend (Go)
Build the CLI binary:
```bash
make build
```
The binary will be created as `miner-ctrl` in the current directory.
For cross-platform builds:
```bash
make build-all
```
Binaries will be in `dist/` directory for Linux, macOS, and Windows.
### Frontend (Angular)
Build the web dashboard:
```bash
cd ui
npm install
npm run build
```
Output will be in `ui/dist/browser/` as `mbe-mining-dashboard.js`.
For development with hot reload:
```bash
cd ui
npm run start
```
This starts a development server on `http://localhost:4200`.
### Desktop Application
Build the Wails desktop app:
```bash
cd cmd/desktop/mining-desktop
npm install
wails3 build
```
Binary will be in `cmd/desktop/mining-desktop/bin/`.
For development mode with hot reload:
```bash
cd cmd/desktop/mining-desktop
wails3 dev
```
### Miner Core (with GPU support)
Build the modified XMRig with GPU support:
```bash
cd miner/core
mkdir build && cd build
# Configure with OpenCL and CUDA
cmake .. -DWITH_OPENCL=ON -DWITH_CUDA=ON
# Build
make -j$(nproc)
```
Binary will be in `miner/core/build/xmrig`.
## Running Tests
### Go Tests
Run all tests:
```bash
make test
```
Run with race detection and coverage:
```bash
make test-release
```
Generate coverage report:
```bash
make coverage
```
Opens an HTML coverage report in your browser.
Run specific tests:
```bash
go test -v ./pkg/mining/... -run TestName
```
### Frontend Tests
Run Angular unit tests:
```bash
cd ui
npm test
```
This runs Karma/Jasmine tests (36 specs).
Run E2E tests with Playwright:
```bash
cd ui
npm run e2e
```
Or run specific test suites:
```bash
# API tests only (no browser)
make e2e-api
# UI tests only
make e2e-ui
# Interactive UI mode
make e2e
```
## Code Quality
### Linting
Format Go code:
```bash
make fmt
```
Run Go linters:
```bash
make lint
```
Format TypeScript/Angular code:
```bash
cd ui
npm run lint
npm run lint:fix
```
### Code Style
**Go:**
- Follow [Effective Go](https://golang.org/doc/effective_go)
- Use `gofmt` for formatting
- Keep functions focused and small
- Write descriptive variable names
- Add comments for exported functions
**TypeScript/Angular:**
- Follow [Angular Style Guide](https://angular.io/guide/styleguide)
- Use TypeScript strict mode
- Prefer composition over inheritance
- Write unit tests for components and services
## Generating Documentation
### Swagger API Docs
Generate Swagger documentation:
```bash
make docs
```
This runs `swag init` and updates `docs/swagger.json` and `docs/swagger.yaml`.
Swagger annotations are in `pkg/mining/service.go`.
### mkdocs Documentation
This documentation is built with mkdocs. To preview locally:
```bash
# Install mkdocs
pip install mkdocs mkdocs-material
# Serve docs locally
mkdocs serve
```
Open `http://127.0.0.1:8000` to view the documentation.
## Development Workflow
### Starting Development Server
Run the full development stack:
```bash
# Terminal 1: Start Go backend
make dev
# Terminal 2: Start Angular dev server
cd ui && npm run start
# Terminal 3: Watch for changes
make watch
```
This provides:
- Backend API on `http://localhost:9090`
- Frontend dev server on `http://localhost:4200`
- Auto-reload on file changes
### Making Changes
1. **Create a branch:**
```bash
git checkout -b feature/my-feature
```
2. **Make your changes**
- Edit source files
- Add tests
- Update documentation
3. **Test your changes:**
```bash
make test
cd ui && npm test
```
4. **Lint your code:**
```bash
make lint
cd ui && npm run lint
```
5. **Commit:**
```bash
git add .
git commit -m "feat: Add my feature"
```
6. **Push and create PR:**
```bash
git push origin feature/my-feature
```
### Commit Message Format
Follow [Conventional Commits](https://www.conventionalcommits.org/):
```
type(scope): description
[optional body]
[optional footer]
```
**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
**Examples:**
```
feat(api): Add endpoint for profile management
fix(miner): Fix XMRig hashrate calculation
docs(readme): Update installation instructions
```
## Debugging
### Go Backend
Debug with Delve:
```bash
# Install delve
go install github.com/go-delve/delve/cmd/dlv@latest
# Start debugging
dlv debug ./cmd/mining -- serve --port 9090
```
Or use your IDE's debugger (VS Code, GoLand, etc.).
### Angular Frontend
Debug in browser:
1. Start dev server: `npm run start`
2. Open browser DevTools (F12)
3. Use Sources tab for breakpoints
4. Console for logs and errors
### Desktop App
Debug Wails app:
```bash
cd cmd/desktop/mining-desktop
wails3 dev --devtools
```
This opens the app with Chrome DevTools enabled.
## Testing Guidelines
### Writing Go Tests
```go
func TestStartMiner(t *testing.T) {
// Arrange
manager := NewManager()
config := &Config{
Pool: "stratum+tcp://pool.test:3333",
Wallet: "test_wallet",
}
// Act
miner, err := manager.StartMiner("xmrig", config)
// Assert
assert.NoError(t, err)
assert.NotNil(t, miner)
assert.Equal(t, "xmrig", miner.GetName())
}
```
### Writing Angular Tests
```typescript
describe('DashboardComponent', () => {
let component: DashboardComponent;
let fixture: ComponentFixture<DashboardComponent>;
beforeEach(() => {
TestBed.configureTestingModule({
imports: [DashboardComponent],
});
fixture = TestBed.createComponent(DashboardComponent);
component = fixture.componentInstance;
});
it('should create', () => {
expect(component).toBeTruthy();
});
it('should fetch miners on init', () => {
spyOn(component.minerService, 'getMiners').and.returnValue(of([]));
component.ngOnInit();
expect(component.minerService.getMiners).toHaveBeenCalled();
});
});
```
## Continuous Integration
The project uses GitHub Actions for CI/CD:
- **Build**: Builds for all platforms on every push
- **Test**: Runs all tests on every PR
- **Lint**: Checks code quality
- **E2E**: Runs Playwright tests
- **Release**: Creates releases on tags
CI configuration is in `.github/workflows/`.
## Common Development Tasks
### Adding a New API Endpoint
1. Add route in `pkg/mining/service.go`:
```go
router.GET("/my-endpoint", s.handleMyEndpoint)
```
2. Implement handler:
```go
// @Summary My endpoint
// @Description Description of what it does
// @Tags miners
// @Produce json
// @Success 200 {object} Response
// @Router /my-endpoint [get]
func (s *Service) handleMyEndpoint(c *gin.Context) {
// Implementation
}
```
3. Generate Swagger docs:
```bash
make docs
```
4. Add tests:
```go
func TestHandleMyEndpoint(t *testing.T) {
// Test implementation
}
```
### Adding a New Angular Component
1. Generate component:
```bash
cd ui
ng generate component components/my-component
```
2. Implement component logic
3. Add styles
4. Write tests
5. Export from module if needed
### Adding a New Miner Implementation
1. Create new file: `pkg/mining/myminer.go`
2. Implement the `Miner` interface
3. Register in manager
4. Add tests
5. Update documentation
See [Architecture Guide](architecture.md) for details.
## Release Process
Releases are handled by GoReleaser:
1. Update `CHANGELOG.md`
2. Tag the release:
```bash
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
```
3. GitHub Actions will automatically:
- Build for all platforms
- Create release artifacts
- Publish to GitHub Releases
For local testing:
```bash
make package
```
This creates a snapshot release in `dist/`.
## Getting Help
- **Documentation**: Check the docs/ folder
- **API Reference**: Use the Swagger UI
- **Issues**: [GitHub Issues](https://github.com/Snider/Mining/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Snider/Mining/discussions)
## Next Steps
- Read the [Architecture Guide](architecture.md)
- Review the [Contributing Guidelines](contributing.md)
- Explore the [API Documentation](../api/index.md)
- See example code in the test files

203
docs/getting-started/index.md Normal file
View file

@ -0,0 +1,203 @@
# Installation
This guide will help you install Mining Platform on your system.
## System Requirements
### Minimum Requirements
- **Operating System**: Linux, macOS, or Windows
- **Go**: Version 1.24 or higher (for building from source)
- **RAM**: 2GB minimum, 4GB recommended
- **Storage**: 1GB free space
### For GPU Mining
- **OpenCL SDK**: For AMD GPU support
- **CUDA Toolkit**: For NVIDIA GPU support
- **GPU Drivers**: Latest drivers for your GPU
### For Development
- **Node.js**: Version 20 or higher
- **CMake**: Version 3.21 or higher
- **Make**: For build automation
## Installation Methods
### Method 1: Pre-built Binaries (Recommended)
Download the latest release for your platform from the [Releases page](https://github.com/Snider/Mining/releases).
#### Linux
```bash
# Download the binary
wget https://github.com/Snider/Mining/releases/latest/download/miner-ctrl-linux-amd64
# Make it executable
chmod +x miner-ctrl-linux-amd64
# Move to PATH
sudo mv miner-ctrl-linux-amd64 /usr/local/bin/miner-ctrl
```
#### macOS
```bash
# Download the binary
curl -L -o miner-ctrl https://github.com/Snider/Mining/releases/latest/download/miner-ctrl-darwin-amd64
# Make it executable
chmod +x miner-ctrl
# Move to PATH
sudo mv miner-ctrl /usr/local/bin/
```
#### Windows
1. Download `miner-ctrl-windows-amd64.exe` from the releases page
2. Rename to `miner-ctrl.exe`
3. Add the directory to your PATH or run from the download location
### Method 2: Install via Go
If you have Go installed, you can install directly:
```bash
go install github.com/Snider/Mining/cmd/mining@latest
```
The binary will be installed to `$GOPATH/bin/mining` (typically `~/go/bin/mining`).
### Method 3: Build from Source
For the latest development version or if you want to contribute:
```bash
# Clone the repository
git clone https://github.com/Snider/Mining.git
cd Mining
# Build the CLI
make build
# The binary will be in the current directory as 'miner-ctrl'
```
## Desktop Application
### Install Pre-built Desktop App
Download the desktop application for your platform:
- **Linux**: `mining-dashboard-linux-amd64` (or `.deb`/`.rpm` packages)
- **macOS**: `mining-dashboard.app` (DMG installer)
- **Windows**: `mining-dashboard-setup.exe` (installer)
### Build Desktop App from Source
```bash
cd cmd/desktop/mining-desktop
# Install dependencies
npm install
# Build for current platform
wails3 build
# Binary will be in: bin/mining-dashboard
```
## Verify Installation
After installation, verify it's working:
```bash
# Check version
miner-ctrl --version
# Show help
miner-ctrl --help
```
You should see output similar to:
```
Mining Platform v1.0.0
A modern cryptocurrency mining management platform
```
## Configuration
### XDG Base Directories
Mining Platform follows XDG Base Directory specifications:
- **Config**: `~/.config/lethean-desktop/`
- **Data**: `~/.local/share/lethean-desktop/miners/`
- **Profiles**: `~/.config/lethean-desktop/mining_profiles.json`
### First Run Setup
On first run, Mining Platform will create the necessary directories automatically. No manual configuration is required.
## Installing Mining Software
Mining Platform can automatically install the mining software it manages:
```bash
# Install XMRig
miner-ctrl install xmrig
# Check installation status
miner-ctrl doctor
```
See the [CLI Guide](../user-guide/cli.md) for more commands.
## Next Steps
Now that you have Mining Platform installed:
1. Follow the [Quick Start Guide](quick-start.md) to begin mining
2. Read the [CLI Guide](../user-guide/cli.md) to learn the commands
3. Explore the [Web Dashboard](../user-guide/web-dashboard.md) for a visual interface
## Troubleshooting
### Permission Errors (Linux/macOS)
If you get permission errors when running commands, ensure the binary is executable:
```bash
chmod +x miner-ctrl
```
### Command Not Found
If the `miner-ctrl` command is not found, ensure it's in your PATH:
```bash
# For Go install
export PATH=$PATH:$GOPATH/bin
# Or use the full path
~/go/bin/mining --help
```
### GPU Mining Not Working
Ensure you have the appropriate SDK installed:
- **AMD GPUs**: Install OpenCL SDK and drivers
- **NVIDIA GPUs**: Install CUDA Toolkit and drivers
Check GPU detection:
```bash
miner-ctrl doctor
```
This will show which GPUs are detected and available for mining.

254
docs/getting-started/quick-start.md Normal file
View file

@ -0,0 +1,254 @@
# Quick Start Guide
Get up and running with Mining Platform in just a few minutes.
## Prerequisites
Ensure you have completed the [Installation](index.md) steps and have `miner-ctrl` installed.
## Step 1: Install Mining Software
First, install the miner software you want to use. For this guide, we'll use XMRig for Monero mining:
```bash
miner-ctrl install xmrig
```
This will download and install XMRig to `~/.local/share/lethean-desktop/miners/xmrig/`.
## Step 2: Start the Mining Service
Start the Mining Platform API server:
```bash
miner-ctrl serve --host localhost --port 9090
```
This starts:
- REST API server on `http://localhost:9090`
- Swagger UI at `http://localhost:9090/api/v1/mining/swagger/index.html`
- Interactive shell for quick commands
## Step 3: Configure Your First Miner
You can configure mining in two ways:
### Option A: Using the CLI
Create a configuration file `xmr-config.json`:
```json
{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_MONERO_WALLET_ADDRESS",
"algo": "rx/0",
"threads": 4
}
```
Start mining:
```bash
miner-ctrl start xmrig --config xmr-config.json
```
### Option B: Using the API
Send a POST request to start mining:
```bash
curl -X POST http://localhost:9090/api/v1/mining/miners/xmrig \
-H "Content-Type: application/json" \
-d '{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_MONERO_WALLET_ADDRESS",
"algo": "rx/0",
"threads": 4
}'
```
## Step 4: Monitor Your Miner
### Check Status
```bash
# List running miners
miner-ctrl list
# Get detailed statistics
miner-ctrl status xmrig
```
### View in Dashboard
Open your browser to `http://localhost:9090` to access the web dashboard, where you can see:
- Real-time hashrate
- Accepted/rejected shares
- Uptime and performance metrics
- Temperature and power usage (if supported)
## Step 5: Save Your Configuration as a Profile
Save your mining configuration for easy reuse:
```bash
curl -X POST http://localhost:9090/api/v1/mining/profiles \
-H "Content-Type: application/json" \
-d '{
"name": "XMR Mining - SupportXMR",
"minerType": "xmrig",
"config": {
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_MONERO_WALLET_ADDRESS",
"algo": "rx/0",
"threads": 4
}
}'
```
Profiles are saved to `~/.config/lethean-desktop/mining_profiles.json`.
## Common Mining Configurations
### Monero (XMR) - CPU Mining
```json
{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_XMR_WALLET",
"algo": "rx/0",
"threads": 4,
"cpuPriority": 3
}
```
### Ethereum Classic (ETC) - GPU Mining
```json
{
"pool": "stratum+tcp://etc.woolypooly.com:3333",
"wallet": "YOUR_ETC_WALLET",
"algo": "etchash",
"cuda": {
"enabled": true,
"devices": [0, 1]
}
}
```
### Ravencoin (RVN) - GPU Mining
```json
{
"pool": "stratum+tcp://rvn.woolypooly.com:3333",
"wallet": "YOUR_RVN_WALLET",
"algo": "kawpow",
"opencl": {
"enabled": true,
"devices": [0]
}
}
```
## Stopping a Miner
```bash
# Via CLI
miner-ctrl stop xmrig
# Via API
curl -X DELETE http://localhost:9090/api/v1/mining/miners/xmrig
```
## Updating Mining Software
Keep your mining software up to date:
```bash
# Check for updates
miner-ctrl update
# Update a specific miner
miner-ctrl install xmrig --force
```
## Desktop Application Quick Start
If you're using the desktop application instead of the CLI:
1. Launch the Mining Dashboard app
2. Click "Install Miner" and select XMRig
3. Go to "Setup Wizard" to configure your first miner
4. Enter your pool URL and wallet address
5. Click "Start Mining"
The desktop app provides the same functionality as the CLI with a graphical interface.
## Pool Recommendations
For beginners, we recommend these pools:
### Monero (XMR)
- **SupportXMR**: `pool.supportxmr.com:3333` (0.6% fee, no registration)
- **P2Pool**: `p2pool.io:3333` (0% fee, decentralized)
- **Nanopool**: `xmr-eu1.nanopool.org:14433` (1.0% fee, mobile app)
### Ethereum Classic (ETC)
- **WoolyPooly**: `etc.woolypooly.com:3333` (0.5% fee)
- **Nanopool**: `etc-eu1.nanopool.org:19999` (1.0% fee)
### Ravencoin (RVN)
- **WoolyPooly**: `rvn.woolypooly.com:3333` (0.5% fee)
- **Flypool**: `rvn.flypool.org:3333` (1.0% fee)
See the [Pool Integration Guide](../reference/pools.md) for comprehensive pool information.
## Next Steps
Now that you're mining:
1. Learn all [CLI commands](../user-guide/cli.md)
2. Explore the [Web Dashboard](../user-guide/web-dashboard.md)
3. Configure [multiple profiles](../user-guide/desktop-app.md) for different coins
4. Read about [pool selection](../reference/pools.md) to optimize your earnings
5. Review the [API documentation](../api/endpoints.md) to integrate with your own apps
## Troubleshooting
### Miner Won't Start
Check the installation:
```bash
miner-ctrl doctor
```
This will verify all installed miners and show any issues.
### Low Hashrate
- Ensure your CPU isn't being throttled due to high temperatures
- Adjust the `threads` parameter (try half your CPU cores)
- Set appropriate `cpuPriority` (1-5, with 5 being highest)
### Connection Refused
Verify the pool is reachable:
```bash
telnet pool.supportxmr.com 3333
```
If the connection fails, try a different pool or port.
### Shares Being Rejected
- Verify your wallet address is correct
- Check that you're using the right algorithm for the pool
- Ensure your miner software is up to date
For more help, see the full [API documentation](../api/index.md) or visit our [GitHub Issues](https://github.com/Snider/Mining/issues).

66
docs/index.md Normal file
View file

@ -0,0 +1,66 @@
# Mining Platform Documentation
Welcome to the Mining Platform documentation. This is a modern, modular cryptocurrency mining management platform with GPU support, RESTful API, and cross-platform desktop application.
## Overview
Mining Platform provides a comprehensive solution for managing cryptocurrency mining operations across multiple algorithms and hardware configurations. Whether you're mining Monero with your CPU, Ethereum Classic with your GPU, or running dual mining operations, Mining Platform gives you the tools to manage it all.
## Key Features
- **Multi-Algorithm Support**: Mine CPU and GPU across RandomX, KawPow, ETChash, ProgPowZ, Blake3, and CryptoNight algorithms
- **Dual Mining**: Run CPU and GPU mining simultaneously with separate pool configurations
- **Profile Management**: Save and quickly switch between mining configurations
- **Real-time Monitoring**: Live hashrate, shares, and performance metrics
- **RESTful API**: Full control via HTTP endpoints with Swagger documentation
- **Web Dashboard**: Embeddable Angular web component for any application
- **Desktop Application**: Native cross-platform app built with Wails v3
- **Mobile Responsive**: Touch-friendly UI optimized for all devices
## Supported Algorithms
| Algorithm | Coin | CPU | GPU (OpenCL) | GPU (CUDA) |
|-----------|------|-----|--------------|------------|
| RandomX | Monero (XMR) | ✅ | ✅ | ✅ |
| KawPow | Ravencoin (RVN) | ❌ | ✅ | ✅ |
| ETChash | Ethereum Classic (ETC) | ❌ | ✅ | ✅ |
| ProgPowZ | Zano (ZANO) | ❌ | ✅ | ✅ |
| Blake3 | Decred (DCR) | ✅ | ✅ | ✅ |
| CryptoNight | Various | ✅ | ✅ | ✅ |
## Quick Links
- **[Getting Started](getting-started/index.md)**: Installation and setup guide
- **[User Guide](user-guide/cli.md)**: Learn how to use the CLI, web dashboard, and desktop app
- **[API Reference](api/index.md)**: RESTful API documentation
- **[Development Guide](development/index.md)**: Contributing and building from source
- **[Pool Integration](reference/pools.md)**: Mining pool configuration and recommendations
## Architecture
The platform consists of three main components:
1. **Core Go Backend** (`pkg/mining/`): Manages miner lifecycle, configuration, and statistics
2. **Web Dashboard** (`ui/`): Angular-based web component for monitoring and control
3. **Desktop Application** (`cmd/desktop/`): Native app with embedded web dashboard
## Managed Mining Software
Mining Platform handles installation and configuration of popular mining software:
- **XMRig**: High-performance CPU/GPU miner for RandomX and CryptoNight
- **T-Rex**: NVIDIA GPU miner for KawPow, Ethash, and more
- **lolMiner**: AMD/NVIDIA GPU miner for Ethash, Beam, Equihash
- **TT-Miner**: NVIDIA GPU miner for Ethash, KawPow, Autolykos2
## Community and Support
- **GitHub**: [Snider/Mining](https://github.com/Snider/Mining)
- **Issue Tracker**: [Report bugs or request features](https://github.com/Snider/Mining/issues)
- **License**: EUPL-1.2
## Next Steps
New to Mining Platform? Start with our [Installation Guide](getting-started/index.md) to get up and running in minutes.
Already installed? Check out the [Quick Start Guide](getting-started/quick-start.md) to begin mining.

494
docs/reference/pools.md Normal file
View file

@ -0,0 +1,494 @@
# Mining Pool Integration Guide
This guide provides comprehensive information about mining pool selection, configuration, and integration with the Mining Platform.
## Overview
Mining pools allow miners to combine their computational power and share rewards. Choosing the right pool is crucial for optimizing your mining profitability and experience.
## Recommended Pools by Coin
### Monero (XMR)
| Pool | URL | Port | Fee | Min Payout | Notes |
|------|-----|------|-----|-----------|-------|
| **SupportXMR** | pool.supportxmr.com | 3333 | 0.6% | 0.003 XMR | Best for beginners, no registration |
| **P2Pool** | p2pool.io | 3333 | 0% | 0.0 XMR | Decentralized, instant payouts |
| **Nanopool** | xmr-eu1.nanopool.org | 14433 | 1.0% | 0.003 XMR | Global network, mobile app |
| **MoneroOcean** | gulf.moneroocean.stream | 10128 | 1.0% | 0.003 XMR | Multi-algo, auto-switching |
| **WoolyPooly** | xmr.woolypooly.com | 3333 | 0.5% | 0.003 XMR | Low fees, merged mining |
### Ethereum Classic (ETC)
| Pool | URL | Port | Fee | Min Payout | Notes |
|------|-----|------|-----|-----------|-------|
| **WoolyPooly** | etc.woolypooly.com | 3333 | 0.5% | 0.01 ETC | Reliable, low fees |
| **Nanopool** | etc-eu1.nanopool.org | 19999 | 1.0% | 0.01 ETC | Established, global |
| **2Miners** | etc.2miners.com | 1010 | 1.0% | 0.01 ETC | PPLNS, no registration |
| **Ethermine** | etc.ethermine.org | 4444 | 1.0% | 0.01 ETC | High performance |
### Ravencoin (RVN)
| Pool | URL | Port | Fee | Min Payout | Notes |
|------|-----|------|-----|-----------|-------|
| **WoolyPooly** | rvn.woolypooly.com | 3333 | 0.5% | 5 RVN | Best overall |
| **Flypool** | rvn.flypool.org | 3333 | 1.0% | 5 RVN | High uptime |
| **2Miners** | rvn.2miners.com | 6060 | 1.0% | 5 RVN | PPLNS rewards |
| **Ravenminer** | ravenminer.com | 3333 | 0.5% | 5 RVN | Community pool |
### Zano (ZANO)
| Pool | URL | Port | Fee | Min Payout | Notes |
|------|-----|------|-----|-----------|-------|
| **WoolyPooly** | zano.woolypooly.com | 3333 | 1.0% | 0.5 ZANO | Primary pool |
| **ZanoPool** | pool.zano.org | 11555 | 1.0% | 0.5 ZANO | Official pool |
## Pool Configuration
### Connection String Format
Most pools use this standard format:
```
protocol://hostname:port
```
**Examples:**
```
stratum+tcp://pool.supportxmr.com:3333
stratum+ssl://pool.supportxmr.com:3334
```
### Authentication Format
Standard authentication uses:
```
Username: WALLET_ADDRESS.WORKER_NAME
Password: x (or empty)
```
**Example:**
```json
{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "4ABC1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890AB",
"username": "4ABC1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890AB.miner1",
"password": "x"
}
```
## Port Configuration
### Standard Port Mapping
Most pools follow this convention:
```
3333 = Standard (auto difficulty) → Try this first
4444 = Medium difficulty
5555 = High difficulty → Use for powerful miners
6666 = Very high difficulty
For TLS/SSL, add 1 to the port:
3334 = Standard over TLS
4445 = Medium over TLS
5556 = High over TLS
```
### Difficulty Selection
Choose a port based on your hashrate:
**Monero (RandomX):**
- 3333 (auto): Any hashrate
- 4444: > 5 KH/s
- 5555: > 20 KH/s
**Ethereum Classic (ETChash):**
- 3333 (auto): Any hashrate
- 4444: > 50 MH/s
- 5555: > 200 MH/s
## Regional Servers
For best performance, choose a server close to your location:
### Nanopool Regions
```
Europe: xmr-eu1.nanopool.org
etc-eu1.nanopool.org
US East: xmr-us-east1.nanopool.org
etc-us-east1.nanopool.org
US West: xmr-us-west1.nanopool.org
etc-us-west1.nanopool.org
Asia: xmr-asia1.nanopool.org
etc-asia1.nanopool.org
```
### MoneroOcean Regions
```
US: gulf.moneroocean.stream
Europe: eu.moneroocean.stream
Asia: asia.moneroocean.stream
```
## Pool Selection Criteria
### For Beginners
Choose pools with:
- Low minimum payout
- No registration required
- Good documentation
- Active community support
- Stable uptime
**Recommended:**
1. SupportXMR (XMR)
2. WoolyPooly (ETC, RVN)
3. Nanopool (all coins)
### For Advanced Users
Consider pools with:
- Lower fees (0.5% or less)
- Advanced features
- API access
- Custom configurations
**Recommended:**
1. P2Pool (XMR) - Decentralized
2. WoolyPooly (all coins) - Low fees
3. SupportXMR (XMR) - Open source
### For Privacy-Focused Mining
Prioritize:
- No registration required
- Decentralized pools
- No personal information collection
**Recommended:**
1. P2Pool (XMR) - Fully decentralized
2. SupportXMR (XMR) - No KYC
3. Any pool without registration
## Configuration Examples
### Monero on SupportXMR
```json
{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_XMR_WALLET_ADDRESS",
"algo": "rx/0",
"threads": 4,
"cpuPriority": 3
}
```
### Ethereum Classic on WoolyPooly
```json
{
"pool": "stratum+tcp://etc.woolypooly.com:3333",
"wallet": "YOUR_ETC_WALLET_ADDRESS",
"algo": "etchash",
"cuda": {
"enabled": true,
"devices": [0, 1]
}
}
```
### Ravencoin on Flypool
```json
{
"pool": "stratum+tcp://rvn.flypool.org:3333",
"wallet": "YOUR_RVN_WALLET_ADDRESS",
"algo": "kawpow",
"opencl": {
"enabled": true,
"devices": [0]
}
}
```
### Dual Mining (CPU + GPU)
Mine Monero on CPU and Ethereum Classic on GPU:
```json
{
"pools": [
{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_XMR_WALLET",
"algo": "rx/0",
"threads": 4
},
{
"pool": "stratum+tcp://etc.woolypooly.com:3333",
"wallet": "YOUR_ETC_WALLET",
"algo": "etchash",
"cuda": {
"enabled": true,
"devices": [0]
}
}
]
}
```
## Fee Comparison
### Monero Pools
| Pool | Fee | Min Payout | Est. Monthly Earnings (1 KH/s) |
|------|-----|-----------|-------------------------------|
| P2Pool | 0% | 0.0 XMR | 100% |
| WoolyPooly | 0.5% | 0.003 XMR | 99.5% |
| SupportXMR | 0.6% | 0.003 XMR | 99.4% |
| Nanopool | 1.0% | 0.003 XMR | 99.0% |
| MoneroOcean | 1.0% | 0.003 XMR | 99.0% |
**Impact:** Fee difference of 0.5% = ~$0.50/month at $100/month earnings
### Ethereum Classic Pools
| Pool | Fee | Min Payout | Est. Monthly Earnings (100 MH/s) |
|------|-----|-----------|----------------------------------|
| WoolyPooly | 0.5% | 0.01 ETC | 99.5% |
| 2Miners | 1.0% | 0.01 ETC | 99.0% |
| Nanopool | 1.0% | 0.01 ETC | 99.0% |
| Ethermine | 1.0% | 0.01 ETC | 99.0% |
## Wallet Address Validation
### Monero (XMR)
Valid XMR addresses:
- **Length:** 95 characters
- **Prefix:** 4 (mainnet) or 8 (testnet)
- **Format:** Base58
Example:
```
4ABC1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890AB1234567890ABCDEF1234567890ABC
```
### Ethereum Classic (ETC)
Valid ETC addresses:
- **Length:** 42 characters (including 0x)
- **Prefix:** 0x
- **Format:** Hexadecimal
Example:
```
0x1234567890123456789012345678901234567890
```
### Ravencoin (RVN)
Valid RVN addresses:
- **Length:** 26-35 characters
- **Prefix:** R
- **Format:** Base58
Example:
```
RAbC123456789aBcDeF123456789XyZ
```
## Testing Pool Connectivity
### Using telnet
```bash
telnet pool.supportxmr.com 3333
```
If successful, you'll see a connection established message.
### Using nc (netcat)
```bash
nc -zv pool.supportxmr.com 3333
```
### Using the Mining Platform
```bash
# Via API
curl -X POST http://localhost:8080/api/v1/mining/test-pool \
-H "Content-Type: application/json" \
-d '{
"pool": "stratum+tcp://pool.supportxmr.com:3333"
}'
```
## Troubleshooting
### Connection Refused
**Possible causes:**
- Pool is down
- Port is blocked by firewall
- Incorrect hostname
**Solutions:**
1. Try TLS port (add 1 to port number)
2. Check pool website for status
3. Try alternative pool
4. Check firewall settings
### High Rejected Shares
**Possible causes:**
- Network latency
- Incorrect algorithm
- Outdated miner software
**Solutions:**
1. Switch to closer regional server
2. Verify algorithm matches pool
3. Update miner software
4. Try different difficulty port
### Very Low Hashrate
**Possible causes:**
- Incorrect thread count
- CPU throttling
- System resource constraints
**Solutions:**
1. Adjust thread count (try half of CPU cores)
2. Check CPU temperature
3. Close other applications
4. Increase CPU priority
### No Payouts
**Possible causes:**
- Minimum payout not reached
- Incorrect wallet address
- Pool payment schedule
**Solutions:**
1. Check pool dashboard for balance
2. Verify wallet address is correct
3. Review pool's payout policy
4. Contact pool support
## Advanced Features
### Pool Failover
Configure backup pools:
```json
{
"pools": [
{
"pool": "stratum+tcp://pool.supportxmr.com:3333",
"wallet": "YOUR_WALLET",
"algo": "rx/0"
},
{
"pool": "stratum+tcp://xmr-eu1.nanopool.org:14433",
"wallet": "YOUR_WALLET",
"algo": "rx/0",
"failover": true
}
]
}
```
### TLS/SSL Encryption
Use encrypted connection:
```json
{
"pool": "stratum+ssl://pool.supportxmr.com:3334",
"wallet": "YOUR_WALLET",
"algo": "rx/0",
"tls": {
"enabled": true,
"fingerprint": "optional_pool_certificate_fingerprint"
}
}
```
### Nicehash Support
For Nicehash-compatible pools:
```json
{
"pool": "stratum+tcp://randomxmonero.auto.nicehash.com:9200",
"wallet": "YOUR_NICEHASH_BTC_ADDRESS",
"algo": "rx/0",
"nicehash": true
}
```
## Pool Database
The Mining Platform includes a comprehensive pool database at:
```
/docs/xmr-pools-database.json
```
This database contains:
- 10+ major mining pools
- 60+ port configurations
- Regional server variants
- Fee structures
- Minimum payouts
- Reliability scores
Load in your application:
```typescript
import poolDatabase from './xmr-pools-database.json';
const supportxmr = poolDatabase.pools.find(p => p.id === 'supportxmr');
console.log(`${supportxmr.name} - ${supportxmr.fee_percent}% fee`);
```
## Best Practices
1. **Start with recommended pools**: Use established pools with good reputation
2. **Monitor performance**: Track hashrate and accepted shares
3. **Use regional servers**: Choose servers close to your location
4. **Enable TLS when possible**: For enhanced security
5. **Configure failover**: Have backup pools configured
6. **Check pool stats regularly**: Monitor your balance and payouts
7. **Join pool community**: Discord, Telegram, or forums
8. **Read pool documentation**: Understand specific pool features
9. **Test before committing**: Mine for a day before large deployments
10. **Update regularly**: Keep miner software up to date
## Resources
- [Pool Research Documentation](../00-START-HERE.md)
- [Pool Integration Guide](../pool-integration-guide.md)
- [Quick Reference](../QUICK-REFERENCE.md)
- [XMR Pool Database](../xmr-pools-database.json)
## Next Steps
- Try the [Quick Start Guide](../getting-started/quick-start.md) to begin mining
- Read about [Algorithms](algorithms.md) supported by the platform
- Explore the [API Documentation](../api/endpoints.md) for automation

16
docs/requirements.txt Normal file
View file

@ -0,0 +1,16 @@
# MkDocs and Material theme
mkdocs>=1.6.0
mkdocs-material>=9.5.0
# Plugins
mkdocs-git-revision-date-localized-plugin>=1.2.0
mkdocs-minify-plugin>=0.8.0
mkdocs-glightbox>=0.4.0
# Additional dependencies for Material theme extensions
pymdown-extensions>=10.7
Pygments>=2.17.0
# Optional but recommended
mkdocs-redirects>=1.2.0
mkdocs-macros-plugin>=1.0.0

39
docs/stylesheets/extra.css Normal file
View file

@ -0,0 +1,39 @@
/* Custom styles for Mining documentation */
:root {
--md-primary-fg-color: #673ab7;
--md-primary-fg-color--light: #9575cd;
--md-primary-fg-color--dark: #512da8;
--md-accent-fg-color: #ab47bc;
}
/* Custom code block styling */
.highlight {
border-radius: 0.2rem;
}
/* Enhanced table styling */
table {
border-radius: 0.2rem;
overflow: hidden;
}
/* Custom admonition colors for mining-specific notes */
.md-typeset .admonition.mining-tip {
border-color: #ab47bc;
}
.md-typeset .admonition.mining-tip > .admonition-title {
background-color: rgba(171, 71, 188, 0.1);
border-color: #ab47bc;
}
/* Improved code inline styling */
code {
border-radius: 0.2rem;
}
/* Better spacing for navigation */
.md-nav__item--nested > .md-nav__link {
font-weight: 500;
}

499
docs/user-guide/cli.md Normal file
View file

@ -0,0 +1,499 @@
# CLI User Guide
The `miner-ctrl` command-line interface provides complete control over Mining Platform from your terminal.
## Installation
See the [Installation Guide](../getting-started/index.md) for installation instructions.
## Global Flags
These flags work with any command:
- `--config string`: Config file path (default: `$HOME/.mining.yaml`)
- `--help`: Show help for the command
## Commands
### serve
Start the mining service and interactive shell.
**Usage:**
```bash
miner-ctrl serve [flags]
```
**Flags:**
- `--host string`: Host to listen on (default: `0.0.0.0`)
- `-p, --port int`: Port to listen on (default: `8080`)
- `-n, --namespace string`: API namespace (default: `/api/v1/mining`)
**Examples:**
```bash
# Start on localhost:9090
miner-ctrl serve --host localhost --port 9090
# Start with custom namespace
miner-ctrl serve --namespace /mining/v2
# Start with interactive shell
miner-ctrl serve
```
When the server is running, you can access:
- REST API: `http://localhost:8080/api/v1/mining/`
- Swagger UI: `http://localhost:8080/api/v1/mining/swagger/index.html`
### start
Start a new miner instance.
**Usage:**
```bash
miner-ctrl start [miner-type] [flags]
```
**Arguments:**
- `miner-type`: Type of miner to start (e.g., `xmrig`)
**Flags:**
- `--config string`: Path to configuration file
- `--pool string`: Mining pool URL
- `--wallet string`: Wallet address
- `--algo string`: Mining algorithm
- `--threads int`: Number of threads to use
**Examples:**
```bash
# Start with config file
miner-ctrl start xmrig --config xmr-config.json
# Start with inline parameters
miner-ctrl start xmrig \
--pool stratum+tcp://pool.supportxmr.com:3333 \
--wallet YOUR_WALLET_ADDRESS \
--algo rx/0 \
--threads 4
# Start GPU mining
miner-ctrl start xmrig \
--pool stratum+tcp://etc.woolypooly.com:3333 \
--wallet YOUR_ETC_WALLET \
--algo etchash \
--cuda
```
### stop
Stop a running miner instance.
**Usage:**
```bash
miner-ctrl stop [miner-name]
```
**Examples:**
```bash
# Stop a miner by name
miner-ctrl stop xmrig
# Stop all miners
miner-ctrl stop --all
```
### status
Get the status and statistics of a running miner.
**Usage:**
```bash
miner-ctrl status [miner-name]
```
**Output includes:**
- Hashrate (current and average)
- Accepted/rejected shares
- Uptime
- Temperature (if supported)
- Power usage (if supported)
**Examples:**
```bash
# Get status of specific miner
miner-ctrl status xmrig
# Get JSON output for scripting
miner-ctrl status xmrig --json
```
### list
List running miners and available miner types.
**Usage:**
```bash
miner-ctrl list [flags]
```
**Flags:**
- `--running`: Show only running miners
- `--available`: Show only available miner types
**Examples:**
```bash
# List all running miners
miner-ctrl list
# Show available miner types
miner-ctrl list --available
# Detailed output
miner-ctrl list --verbose
```
### install
Install or update a miner binary.
**Usage:**
```bash
miner-ctrl install [miner-type] [flags]
```
**Flags:**
- `--force`: Force reinstall even if already installed
- `--version string`: Install specific version
**Examples:**
```bash
# Install XMRig
miner-ctrl install xmrig
# Install specific version
miner-ctrl install xmrig --version 6.21.0
# Force reinstall
miner-ctrl install xmrig --force
```
Miners are installed to `~/.local/share/lethean-desktop/miners/[miner-type]/`.
### uninstall
Uninstall a miner and remove its files.
**Usage:**
```bash
miner-ctrl uninstall [miner-type]
```
**Examples:**
```bash
# Uninstall XMRig
miner-ctrl uninstall xmrig
# Uninstall with confirmation
miner-ctrl uninstall xmrig --confirm
```
### update
Check for updates to installed miners.
**Usage:**
```bash
miner-ctrl update [flags]
```
**Flags:**
- `--check-only`: Only check for updates, don't install
- `--all`: Update all miners with available updates
**Examples:**
```bash
# Check for updates
miner-ctrl update --check-only
# Update all miners
miner-ctrl update --all
# Update specific miner
miner-ctrl update xmrig
```
### doctor
Check the status of all installed miners and system configuration.
**Usage:**
```bash
miner-ctrl doctor
```
**Output includes:**
- Installed miners and versions
- GPU detection (OpenCL/CUDA)
- System resources
- Configuration file locations
- Potential issues and recommendations
**Examples:**
```bash
# Run full diagnostic
miner-ctrl doctor
# Output to file for troubleshooting
miner-ctrl doctor > system-info.txt
```
### completion
Generate shell completion scripts.
**Usage:**
```bash
miner-ctrl completion [shell]
```
**Supported shells:**
- `bash`
- `zsh`
- `fish`
- `powershell`
**Examples:**
```bash
# Bash completion
miner-ctrl completion bash > /etc/bash_completion.d/miner-ctrl
# Zsh completion
miner-ctrl completion zsh > "${fpath[1]}/_miner-ctrl"
# Fish completion
miner-ctrl completion fish > ~/.config/fish/completions/miner-ctrl.fish
```
## Configuration File
Create a config file at `~/.mining.yaml`:
```yaml
server:
host: localhost
port: 9090
namespace: /api/v1/mining
defaults:
miner: xmrig
threads: 4
cpuPriority: 3
profiles:
- name: XMR
pool: stratum+tcp://pool.supportxmr.com:3333
wallet: YOUR_XMR_WALLET
algo: rx/0
- name: ETC
pool: stratum+tcp://etc.woolypooly.com:3333
wallet: YOUR_ETC_WALLET
algo: etchash
```
Load a profile:
```bash
miner-ctrl start --profile XMR
```
## Interactive Shell
When you run `miner-ctrl serve` without backgrounding it, you get an interactive shell:
```
Mining Platform v1.0.0
API Server running on http://localhost:9090
Type 'help' for available commands
mining> help
Available commands:
list - List running miners
start - Start a miner
stop - Stop a miner
status - Get miner status
profiles - Manage profiles
exit - Exit shell
mining> list
Running miners:
xmrig - Hashrate: 4520 H/s, Shares: 42/0
mining> status xmrig
Miner: xmrig
Status: Running
Hashrate: 4520 H/s
Accepted Shares: 42
Rejected Shares: 0
Uptime: 2h 15m
```
## Output Formats
Most commands support multiple output formats:
```bash
# Human-readable (default)
miner-ctrl list
# JSON for scripting
miner-ctrl list --output json
# YAML
miner-ctrl status xmrig --output yaml
# Table format
miner-ctrl list --output table
```
## Environment Variables
Configure behavior with environment variables:
```bash
# Set config file location
export MINING_CONFIG=~/.config/mining.yaml
# Set data directory
export MINING_DATA_DIR=~/.local/share/mining
# Set log level
export MINING_LOG_LEVEL=debug
# Start server
miner-ctrl serve
```
## Examples
### Basic Mining Workflow
```bash
# 1. Install miner
miner-ctrl install xmrig
# 2. Verify installation
miner-ctrl doctor
# 3. Start mining
miner-ctrl start xmrig \
--pool stratum+tcp://pool.supportxmr.com:3333 \
--wallet YOUR_WALLET \
--algo rx/0
# 4. Monitor
miner-ctrl status xmrig
# 5. Stop when done
miner-ctrl stop xmrig
```
### Dual Mining (CPU + GPU)
```bash
# Start CPU mining for Monero
miner-ctrl start xmrig-cpu \
--pool stratum+tcp://pool.supportxmr.com:3333 \
--wallet YOUR_XMR_WALLET \
--algo rx/0 \
--threads 4
# Start GPU mining for Ethereum Classic
miner-ctrl start xmrig-gpu \
--pool stratum+tcp://etc.woolypooly.com:3333 \
--wallet YOUR_ETC_WALLET \
--algo etchash \
--cuda
# Monitor both
miner-ctrl list
```
### Automated Monitoring
```bash
# Create a monitoring script
cat > monitor.sh << 'EOF'
#!/bin/bash
while true; do
clear
echo "=== Mining Status ==="
miner-ctrl status xmrig --output json | jq '.hashrate, .shares'
sleep 10
done
EOF
chmod +x monitor.sh
./monitor.sh
```
## Troubleshooting
### Command Not Found
Ensure `miner-ctrl` is in your PATH:
```bash
which miner-ctrl
# If not found, add to PATH or use full path
```
### Permission Denied
On Linux, you may need to run with appropriate permissions:
```bash
# Grant execute permission
chmod +x miner-ctrl
# Or run with sudo if needed (not recommended)
sudo miner-ctrl doctor
```
### Miner Won't Start
Check logs for errors:
```bash
# Enable debug logging
miner-ctrl --log-level debug start xmrig ...
# Check system journal (Linux)
journalctl -u mining-service
```
### Port Already in Use
If port 8080 is already in use:
```bash
# Use a different port
miner-ctrl serve --port 9090
```
## Next Steps
- Explore the [Web Dashboard](web-dashboard.md) for visual management
- Try the [Desktop Application](desktop-app.md) for a native experience
- Read the [API Documentation](../api/endpoints.md) for integration
- See [Pool Integration Guide](../reference/pools.md) for pool recommendations

561
docs/user-guide/desktop-app.md Normal file
View file

@ -0,0 +1,561 @@
# Desktop Application User Guide
The Mining Platform desktop application provides a native cross-platform experience built with Wails v3 and Angular.
## Overview
The desktop app combines the power of the Mining Platform backend with a modern desktop interface, offering:
- Native application performance
- System tray integration
- Auto-start on boot
- Local-first operation
- Embedded web dashboard
- No browser required
## Installation
### Download Pre-built Application
Download the appropriate version for your platform from the [Releases page](https://github.com/Snider/Mining/releases):
**Linux:**
- `mining-dashboard-linux-amd64` (standalone binary)
- `mining-dashboard_amd64.deb` (Debian/Ubuntu)
- `mining-dashboard_amd64.rpm` (Fedora/RHEL)
**macOS:**
- `mining-dashboard.dmg` (drag and drop installer)
- `mining-dashboard.app.zip` (extract and run)
**Windows:**
- `mining-dashboard-setup.exe` (installer)
- `mining-dashboard-portable.exe` (no installation required)
### Linux Installation
#### Using DEB Package
```bash
sudo dpkg -i mining-dashboard_amd64.deb
```
#### Using RPM Package
```bash
sudo rpm -i mining-dashboard_amd64.rpm
```
#### Standalone Binary
```bash
chmod +x mining-dashboard-linux-amd64
./mining-dashboard-linux-amd64
```
### macOS Installation
1. Open the DMG file
2. Drag Mining Dashboard to Applications
3. Open from Applications folder
4. If blocked by Gatekeeper:
- Go to System Preferences → Security & Privacy
- Click "Open Anyway"
### Windows Installation
#### Using Installer
1. Run `mining-dashboard-setup.exe`
2. Follow installation wizard
3. Launch from Start Menu
#### Portable Version
1. Extract `mining-dashboard-portable.exe`
2. Run directly (no installation needed)
3. Settings saved in same folder
## First Launch
When you first launch the desktop app:
1. **Welcome Screen**: Brief introduction to features
2. **Setup Wizard**: Optional guided setup
- Install mining software
- Configure first miner
- Select pools
3. **Main Dashboard**: Ready to use
## User Interface
### Main Window
The main window contains:
**Menu Bar** (top):
- File: New profile, Import/Export, Preferences, Exit
- Miners: Install, Start, Stop, Update
- View: Refresh, Toggle Fullscreen, Developer Tools
- Help: Documentation, Check for Updates, About
**Sidebar** (left):
- Dashboard: Overview and quick stats
- Miners: Running and available miners
- Profiles: Saved configurations
- Statistics: Charts and analytics
- Pools: Pool information and recommendations
- Admin: System settings and diagnostics
- Settings: Application preferences
**Content Area** (center):
- Page-specific content
- Real-time data updates
- Interactive controls
**Status Bar** (bottom):
- Connection status
- Active miners count
- Total hashrate
- Last update time
### System Tray
The app runs in the system tray when minimized:
**Tray Icon**: Shows mining status
- Green: Mining active
- Gray: Idle
- Red: Error/stopped
**Tray Menu** (right-click):
- Show/Hide window
- Quick start mining
- Pause all miners
- Exit application
### Dashboard Page
The dashboard provides an at-a-glance view:
- **Active Miners Card**: Count and quick actions
- **Hashrate Card**: Total and per-miner breakdown
- **Shares Card**: Accepted/rejected statistics
- **Earnings Card**: Estimated daily/monthly earnings
- **Recent Activity**: Timeline of events
- **Quick Actions**: Common tasks
### Miners Page
Manage your mining operations:
**Running Miners:**
- List of active miners with status
- Real-time hashrate and statistics
- Stop/pause controls
- View detailed logs
**Available Miners:**
- Installable mining software
- Version information
- Install/update buttons
**Actions:**
- Add new miner
- Import configuration
- Batch operations
### Profiles Page
Save and manage mining configurations:
**Profile Cards:**
- Profile name and description
- Coin and algorithm
- Pool information
- Quick start button
**Profile Actions:**
- Create new profile
- Edit existing profile
- Duplicate profile
- Delete profile
- Export/import profiles
**Profile Editor:**
- Basic settings (name, coin, pool)
- Advanced settings (threads, priority, etc.)
- Test configuration
- Save or cancel
### Statistics Page
Detailed performance analytics:
**Charts:**
- Hashrate over time (line chart)
- Share distribution (pie chart)
- Pool comparison (bar chart)
- Temperature/power (multi-line)
**Time Ranges:**
- Last hour
- Last 24 hours
- Last 7 days
- Last 30 days
- Custom range
**Export:**
- Export to CSV
- Export to JSON
- Generate report (PDF)
### Pools Page
Mining pool information and management:
**Recommended Pools:**
- Top pools by reliability
- Fee comparison
- Payout information
- One-click configuration
**Pool Testing:**
- Test pool connectivity
- Latency measurement
- Difficulty estimation
**Custom Pools:**
- Add custom pool
- Edit pool details
- Remove pool
### Admin Page
System administration and diagnostics:
**System Information:**
- OS and architecture
- CPU information
- GPU detection (OpenCL/CUDA)
- Memory usage
**Miner Management:**
- Install/uninstall miners
- Update all miners
- Clear miner data
**Diagnostics:**
- Run system check
- View logs
- Export diagnostic report
**Advanced:**
- API endpoint configuration
- Data directory location
- Debug mode toggle
### Settings Page
Application preferences:
**General:**
- Language selection
- Theme (light/dark/auto)
- Auto-start on boot
- Minimize to tray
**Notifications:**
- Enable desktop notifications
- Sound alerts
- Notification types (start, stop, errors)
**Updates:**
- Auto-check for updates
- Update channel (stable/beta)
- Auto-install updates
**Mining:**
- Auto-refresh interval
- Default miner type
- Default CPU threads
- Power saving mode
**Advanced:**
- Enable developer tools
- API base URL (for custom backend)
- Log level
- Data retention period
## Using the Desktop App
### Starting Mining
**Method 1: Quick Start**
1. Click "Quick Start" on Dashboard
2. Select a profile (or use default)
3. Click "Start"
**Method 2: From Profile**
1. Go to Profiles page
2. Click "Start" on desired profile
3. Miner starts immediately
**Method 3: Manual Configuration**
1. Go to Miners page
2. Click "Add Miner"
3. Configure settings
4. Click "Start Mining"
### Monitoring Performance
**Real-time View:**
1. Go to Dashboard
2. View live hashrate and shares
3. Click miner card for details
**Detailed Statistics:**
1. Go to Statistics page
2. Select miner from dropdown
3. Choose time range
4. View charts and metrics
**System Tray:**
- Hover over tray icon for quick stats
- Click icon to show/hide window
### Managing Profiles
**Create Profile:**
1. Go to Profiles page
2. Click "New Profile"
3. Enter details:
- Profile name
- Select coin
- Choose pool
- Enter wallet address
- Configure hardware
4. Click "Save"
**Edit Profile:**
1. Click "Edit" on profile card
2. Modify settings
3. Click "Save Changes"
**Use Profile:**
1. Click "Start" on profile card
2. Monitor on Dashboard
3. Click "Stop" when done
### Auto-Start Configuration
To start mining automatically on boot:
1. Go to Settings
2. Enable "Auto-start on boot"
3. Select default profile
4. Configure delay (optional)
The app will:
- Launch on system startup
- Wait for configured delay
- Start mining with selected profile
- Minimize to tray
### Updating Mining Software
**Auto Update (Recommended):**
1. Go to Settings → Updates
2. Enable "Auto-check for updates"
3. Updates happen automatically
**Manual Update:**
1. Go to Admin page
2. Click "Check for Updates"
3. Click "Update All" or select specific miner
4. Wait for download and installation
### Installing Additional Miners
1. Go to Admin page
2. Find miner in "Available Miners"
3. Click "Install"
4. Wait for download
5. Miner appears in Miners page
## Keyboard Shortcuts
Global shortcuts:
- `Ctrl+N`: New profile
- `Ctrl+O`: Open profiles
- `Ctrl+S`: Save current form
- `Ctrl+W`: Close window
- `Ctrl+Q`: Quit application
- `Ctrl+R`: Refresh data
- `Ctrl+,`: Open settings
- `F5`: Refresh current page
- `F11`: Toggle fullscreen
- `F12`: Open developer tools
Mining shortcuts:
- `Ctrl+M`: Start mining (quick start)
- `Ctrl+Shift+M`: Stop all miners
- `Ctrl+P`: Pause/resume mining
Navigation:
- `Ctrl+1-7`: Switch between pages
- `Ctrl+Tab`: Next page
- `Ctrl+Shift+Tab`: Previous page
## Command Line Arguments
Launch the app with arguments:
```bash
# Start minimized to tray
mining-dashboard --minimized
# Start with specific profile
mining-dashboard --profile "XMR Mining"
# Start mining immediately
mining-dashboard --auto-start
# Use custom data directory
mining-dashboard --data-dir ~/my-mining-data
# Enable debug mode
mining-dashboard --debug
```
## Data Storage
Application data is stored in:
**Linux:**
- Config: `~/.config/lethean-desktop/`
- Data: `~/.local/share/lethean-desktop/`
- Logs: `~/.local/share/lethean-desktop/logs/`
**macOS:**
- Config: `~/Library/Application Support/lethean-desktop/`
- Data: `~/Library/Application Support/lethean-desktop/`
- Logs: `~/Library/Logs/lethean-desktop/`
**Windows:**
- Config: `%APPDATA%\lethean-desktop\`
- Data: `%LOCALAPPDATA%\lethean-desktop\`
- Logs: `%LOCALAPPDATA%\lethean-desktop\logs\`
## Backing Up Data
To back up your profiles and settings:
**Method 1: Export Profiles**
1. Go to Profiles page
2. Click "Export All"
3. Save JSON file
4. Store file safely
**Method 2: Copy Data Directory**
```bash
# Linux/macOS
cp -r ~/.config/lethean-desktop ~/backup/
# Windows (PowerShell)
Copy-Item -Path "$env:APPDATA\lethean-desktop" -Destination "C:\backup\" -Recurse
```
## Troubleshooting
### App Won't Start
**Linux:**
```bash
# Check for errors
./mining-dashboard --debug
# Check permissions
chmod +x mining-dashboard-linux-amd64
```
**macOS:**
- Remove from quarantine:
```bash
xattr -cr /Applications/Mining\ Dashboard.app
```
**Windows:**
- Run as administrator
- Check antivirus isn't blocking
- Install Visual C++ Redistributable if needed
### Miner Won't Start
1. Go to Admin → Diagnostics
2. Click "Run System Check"
3. Review errors and warnings
4. Follow suggested fixes
### High CPU Usage
1. Go to Settings → Mining
2. Enable "Power Saving Mode"
3. Reduce auto-refresh interval
4. Close unnecessary pages
### Data Not Syncing
1. Check internet connection
2. Verify API endpoint in Settings
3. Restart application
4. Clear cache: Settings → Advanced → Clear Cache
### Window Won't Restore from Tray
1. Right-click tray icon
2. Select "Show Window"
3. If still hidden, restart application
## Uninstalling
### Linux
**DEB Package:**
```bash
sudo dpkg -r mining-dashboard
```
**RPM Package:**
```bash
sudo rpm -e mining-dashboard
```
**Standalone:**
```bash
rm ~/mining-dashboard
rm -rf ~/.config/lethean-desktop
rm -rf ~/.local/share/lethean-desktop
```
### macOS
1. Quit the application
2. Move to Trash from Applications
3. Delete data (optional):
```bash
rm -rf ~/Library/Application\ Support/lethean-desktop
```
### Windows
1. Use Programs and Features (Control Panel)
2. Or run uninstaller from Start Menu
3. Delete data (optional):
- Navigate to `%APPDATA%\lethean-desktop`
- Delete folder
## Next Steps
- Read the [CLI Guide](cli.md) for command-line usage
- Explore the [Web Dashboard](web-dashboard.md) features
- Review [Pool Recommendations](../reference/pools.md)
- Check the [API Documentation](../api/endpoints.md)

415
docs/user-guide/web-dashboard.md Normal file
View file

@ -0,0 +1,415 @@
# Web Dashboard User Guide
The Mining Platform web dashboard provides a visual interface for monitoring and managing your mining operations.
## Overview
The web dashboard is an Angular-based web component that can be:
- Accessed via the built-in server
- Embedded in any web application
- Used standalone in a browser
## Accessing the Dashboard
### Via Built-in Server
Start the Mining Platform server:
```bash
miner-ctrl serve --port 9090
```
Then open your browser to:
```
http://localhost:9090
```
### Embedding in Your Application
The dashboard is available as a standalone web component:
```html
<!DOCTYPE html>
<html>
<head>
<title>Mining Dashboard</title>
<script type="module" src="./mbe-mining-dashboard.js"></script>
</head>
<body>
<snider-mining api-base-url="http://localhost:9090/api/v1/mining"></snider-mining>
</body>
</html>
```
### Component Properties
The web component accepts these attributes:
- `api-base-url`: Base URL for the API (required)
- `theme`: UI theme (`light` or `dark`)
- `auto-refresh`: Auto-refresh interval in seconds (default: 10)
- `locale`: Locale for number formatting (default: `en-US`)
Example with all properties:
```html
<snider-mining
api-base-url="http://localhost:9090/api/v1/mining"
theme="dark"
auto-refresh="5"
locale="en-US">
</snider-mining>
```
## Dashboard Features
### Home Page
The home page displays an overview of your mining operations:
- **Active Miners**: Number of currently running miners
- **Total Hashrate**: Combined hashrate across all miners
- **Total Shares**: Accepted and rejected shares
- **System Resources**: CPU and GPU usage
### Miners Page
View and manage all your miners:
- **Running Miners**: List of active mining operations
- Real-time hashrate
- Pool connection status
- Accepted/rejected shares
- Uptime
- Quick stop button
- **Available Miners**: Software you can install
- Installation status
- Version information
- Quick install button
### Profiles Page
Manage your mining configurations:
- **Saved Profiles**: Reusable mining configurations
- Create, edit, and delete profiles
- One-click start from profile
- Import/export profiles
- **Profile Editor**: Configure mining parameters
- Pool selection
- Wallet address
- Algorithm selection
- CPU/GPU settings
- Advanced options
### Setup Wizard
A guided setup process for beginners:
1. **Select Coin**: Choose which cryptocurrency to mine
2. **Choose Pool**: Select from recommended pools
3. **Enter Wallet**: Input your wallet address
4. **Configure Hardware**: Select CPU or GPU mining
5. **Review & Start**: Confirm settings and start mining
### Admin Page
Advanced configuration and system management:
- **System Information**
- Operating system
- Go version
- Total RAM
- Detected GPUs (OpenCL/CUDA)
- **Miner Management**
- Install/uninstall miners
- Update miners
- View logs
- Run diagnostics
- **Settings**
- Auto-start configuration
- Notification preferences
- API endpoint configuration
- Theme selection
### Statistics Dashboard
Detailed performance metrics:
- **Hashrate Charts**
- Real-time hashrate graph
- Historical data (5 min high-res, 24h low-res)
- Per-miner breakdown
- **Shares Analysis**
- Accepted vs rejected shares
- Share submission rate
- Pool response time
- **Earnings Estimates**
- Estimated daily earnings
- Estimated monthly earnings
- Based on current hashrate and coin difficulty
## Mobile Interface
The dashboard is fully responsive and optimized for mobile devices:
- **Drawer Navigation**: Swipe from left edge to open menu
- **Touch-Optimized**: Large buttons and touch targets
- **Adaptive Layout**: Single-column layout on small screens
- **Pull to Refresh**: Pull down on any page to refresh data
### Mobile Navigation
On mobile devices (screens < 768px):
- Tap the hamburger menu (☰) to open navigation
- Swipe left to close the drawer
- Tap outside the drawer to close it
## Using the Dashboard
### Starting a Miner
1. Go to **Miners** page
2. Click **Add Miner** or select a profile
3. Fill in the configuration:
- Pool URL
- Wallet address
- Algorithm
- Number of threads (CPU) or devices (GPU)
4. Click **Start Mining**
### Monitoring Performance
1. Go to **Statistics** page
2. Select the miner from the dropdown
3. View real-time charts:
- Hashrate over time
- Share acceptance rate
- Temperature (if supported)
### Creating a Profile
1. Go to **Profiles** page
2. Click **New Profile**
3. Enter profile details:
- Name (e.g., "XMR - SupportXMR")
- Miner type (xmrig, etc.)
- Pool configuration
4. Click **Save**
To use the profile:
1. Click **Start** on the profile card
2. The miner will start with the saved configuration
### Stopping a Miner
1. Go to **Miners** page
2. Find the running miner
3. Click the **Stop** button
4. Confirm if prompted
## Keyboard Shortcuts
The dashboard supports keyboard shortcuts for common actions:
- `Ctrl+N`: New miner/profile
- `Ctrl+S`: Save current form
- `Ctrl+R`: Refresh data
- `Esc`: Close modal/drawer
- `?`: Show keyboard shortcuts help
## Theme Customization
Switch between light and dark themes:
1. Go to **Settings** (Admin page)
2. Select **Theme**
3. Choose **Light** or **Dark**
4. Theme is saved to localStorage
Or set via HTML attribute:
```html
<snider-mining theme="dark"></snider-mining>
```
## Auto-Refresh
The dashboard automatically refreshes data every 10 seconds by default.
To customize:
```html
<snider-mining auto-refresh="5"></snider-mining>
```
To disable auto-refresh:
```html
<snider-mining auto-refresh="0"></snider-mining>
```
## Notifications
The dashboard can display browser notifications for important events:
- Miner started
- Miner stopped
- Miner crashed
- Low hashrate warning
- Share rejection spike
Enable notifications:
1. Go to **Settings**
2. Enable **Desktop Notifications**
3. Grant permission when prompted by browser
## Exporting Data
Export your profiles or statistics:
### Export Profiles
1. Go to **Profiles** page
2. Click **Export**
3. Choose format (JSON or CSV)
4. Save file
### Import Profiles
1. Go to **Profiles** page
2. Click **Import**
3. Select your exported file
4. Profiles will be added to your list
### Export Statistics
1. Go to **Statistics** page
2. Select date range
3. Click **Export**
4. Choose format (CSV or JSON)
5. Save file
## Troubleshooting
### Dashboard Won't Load
Check that the server is running:
```bash
curl http://localhost:9090/api/v1/mining/info
```
If no response, start the server:
```bash
miner-ctrl serve --port 9090
```
### "Connection Refused" Error
Ensure the `api-base-url` matches your server:
```html
<snider-mining api-base-url="http://localhost:9090/api/v1/mining"></snider-mining>
```
### Data Not Updating
1. Check auto-refresh is enabled
2. Verify API endpoint is reachable
3. Check browser console for errors (F12)
4. Try manual refresh (Ctrl+R)
### Profile Won't Start
1. Verify miner software is installed
2. Check wallet address is valid
3. Test pool connectivity
4. Review error message in notification
### Charts Not Showing
1. Ensure miner has been running for at least 1 minute
2. Check that statistics are being collected
3. Verify browser supports Canvas/SVG
4. Try clearing browser cache
## Performance Tips
### Reduce CPU Usage
If the dashboard is using too much CPU:
1. Increase auto-refresh interval:
```html
<snider-mining auto-refresh="30"></snider-mining>
```
2. Disable charts on Statistics page when not needed
3. Close unnecessary browser tabs
### Optimize for Low-End Devices
For Raspberry Pi or low-power devices:
1. Use light theme (uses less GPU)
2. Set auto-refresh to 60 seconds
3. Limit number of active miners shown
4. Disable desktop notifications
## Advanced Usage
### Custom Styling
Override dashboard styles with CSS:
```html
<style>
snider-mining {
--primary-color: #00ff00;
--background-color: #1a1a1a;
--text-color: #ffffff;
}
</style>
```
### JavaScript API
Interact with the component via JavaScript:
```javascript
const dashboard = document.querySelector('snider-mining');
// Listen for events
dashboard.addEventListener('miner-started', (e) => {
console.log('Miner started:', e.detail);
});
dashboard.addEventListener('miner-stopped', (e) => {
console.log('Miner stopped:', e.detail);
});
// Programmatic control
dashboard.startMiner({
type: 'xmrig',
config: { /* ... */ }
});
dashboard.stopMiner('xmrig');
```
## Next Steps
- Try the [Desktop Application](desktop-app.md) for a native experience
- Learn about [Pool Selection](../reference/pools.md)
- Explore the [REST API](../api/endpoints.md) for automation
- Read the [Development Guide](../development/index.md) to contribute

214
mkdocs.yml
View file

@ -1,39 +1,74 @@
site_name: Mining Dashboard site_name: Mining - Cryptocurrency Mining Management
docs_dir: site-docs site_description: A modular cryptocurrency mining management system with CLI, API, and desktop applications
site_description: Multi-Miner Management System - Control XMRig, TT-Miner and more from a single dashboard site_author: Mining Project Contributors
site_author: Built with Claude Code site_url: https://snider.github.io/Mining/
repo_url: https://github.com/Snider/Mining
repo_name: Snider/Mining repo_name: Snider/Mining
repo_url: https://github.com/Snider/Mining
edit_uri: edit/main/docs/
docs_dir: docs
theme: theme:
name: material name: material
palette: palette:
- scheme: slate # Palette toggle for dark mode (default)
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: deep purple primary: deep purple
accent: lime accent: purple
toggle: toggle:
icon: material/brightness-4 icon: material/brightness-4
name: Switch to light mode name: Switch to light mode
- scheme: default # Palette toggle for light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: deep purple primary: deep purple
accent: lime accent: purple
toggle: toggle:
icon: material/brightness-7 icon: material/brightness-7
name: Switch to dark mode name: Switch to dark mode
features: features:
- navigation.instant
- navigation.instant.prefetch
- navigation.instant.progress
- navigation.tracking
- navigation.tabs - navigation.tabs
- navigation.tabs.sticky
- navigation.sections - navigation.sections
- navigation.expand - navigation.expand
- navigation.path
- navigation.top - navigation.top
- navigation.footer
- toc.follow
- toc.integrate
- search.suggest
- search.highlight
- search.share
- content.code.copy - content.code.copy
- content.code.annotate - content.code.annotate
- content.tabs.link
- content.action.edit
- content.action.view
icon: icon:
repo: fontawesome/brands/github repo: fontawesome/brands/github
logo: assets/logo.svg edit: material/pencil
favicon: assets/favicon.ico view: material/eye
font:
text: Roboto
code: Roboto Mono
plugins: plugins:
- search - search:
separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
- git-revision-date-localized:
enable_creation_date: true
type: timeago
- minify:
minify_html: true
- glightbox: - glightbox:
touchNavigation: true touchNavigation: true
loop: false loop: false
@ -45,10 +80,35 @@ plugins:
draggable: true draggable: true
markdown_extensions: markdown_extensions:
- abbr
- admonition
- attr_list
- def_list
- footnotes
- md_in_html
- tables
- toc:
permalink: true
toc_depth: 3
- pymdownx.arithmatex:
generic: true
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.highlight: - pymdownx.highlight:
anchor_linenums: true anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite - pymdownx.inlinehilite
- pymdownx.snippets - pymdownx.keys
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.snippets:
check_paths: true
- pymdownx.superfences: - pymdownx.superfences:
custom_fences: custom_fences:
- name: mermaid - name: mermaid
@ -56,51 +116,117 @@ markdown_extensions:
format: !!python/name:pymdownx.superfences.fence_code_format format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed: - pymdownx.tabbed:
alternate_style: true alternate_style: true
- pymdownx.details - pymdownx.tasklist:
- admonition custom_checkbox: true
- tables - pymdownx.tilde
- attr_list
- md_in_html
- toc:
permalink: true
extra: extra:
social: social:
- icon: fontawesome/brands/github - icon: fontawesome/brands/github
link: https://github.com/Snider/Mining link: https://github.com/Snider/Mining
- icon: fontawesome/brands/docker
link: https://hub.docker.com/r/snider/mining
generator: false generator: false
version:
provider: mike
copyright: Built with Claude Code - AI-Powered Development extra_css:
- stylesheets/extra.css
copyright: Copyright &copy; 2025 Mining Project Contributors
nav: nav:
- Home: index.md - Home: index.md
- Getting Started: - Getting Started:
- Introduction: getting-started/introduction.md
- Installation: getting-started/installation.md - Installation: getting-started/installation.md
- Quick Start: getting-started/quickstart.md - Quick Start: getting-started/quickstart.md
- Configuration: getting-started/configuration.md - Configuration: getting-started/configuration.md
- Features: - First Mining Session: getting-started/first-session.md
- Dashboard: features/dashboard.md
- Mining Profiles: features/profiles.md
- Console & Logs: features/console.md
- Multi-Miner Support: features/multi-miner.md
- Historical Data: features/history.md
- P2P Multi-Node: features/p2p-multinode.md
- User Interface:
- Overview: ui/overview.md
- Screenshots: ui/screenshots.md
- API Reference:
- REST API: api/rest-api.md
- Endpoints: api/endpoints.md
- CLI Reference: - CLI Reference:
- Commands: cli/commands.md - Overview: cli/overview.md
- Examples: cli/examples.md - serve: cli/serve.md
- start: cli/start.md
- stop: cli/stop.md
- status: cli/status.md
- install: cli/install.md
- uninstall: cli/uninstall.md
- update: cli/update.md
- list: cli/list.md
- doctor: cli/doctor.md
- profiles: cli/profiles.md
- API Reference:
- Overview: api/overview.md
- Authentication: api/authentication.md
- System Endpoints: api/system.md
- Miner Endpoints: api/miners.md
- Profile Endpoints: api/profiles.md
- Stats Endpoints: api/stats.md
- Swagger UI: api/swagger.md
- Error Handling: api/errors.md
- Web Dashboard:
- Overview: dashboard/overview.md
- Installation: dashboard/installation.md
- Web Component: dashboard/web-component.md
- Features: dashboard/features.md
- Configuration: dashboard/configuration.md
- Customization: dashboard/customization.md
- Desktop Application:
- Overview: desktop/overview.md
- Installation: desktop/installation.md
- Building from Source: desktop/building.md
- Platform Support: desktop/platforms.md
- Configuration: desktop/configuration.md
- Troubleshooting: desktop/troubleshooting.md
- Development Guide:
- Setup: development/setup.md
- Project Structure: development/structure.md
- Building: development/building.md
- Testing: development/testing.md
- E2E Tests: development/e2e-tests.md
- Code Style: development/code-style.md
- Contributing: development/contributing.md
- Release Process: development/releases.md
- Architecture: - Architecture:
- Overview: architecture/overview.md - Overview: architecture/overview.md
- Backend: architecture/backend.md - Go Backend: architecture/backend.md
- Frontend: architecture/frontend.md - Miner Interface: architecture/miner-interface.md
- Development: - Manager System: architecture/manager.md
- Contributing: development/contributing.md - REST Service: architecture/rest-service.md
- Building: development/building.md - XMRig Implementation: architecture/xmrig.md
- About: - Profile System: architecture/profiles.md
- Built with Claude: about/claude.md - Stats Collection: architecture/stats.md
- Changelog: about/changelog.md - XDG Directories: architecture/xdg.md
- Pool Integration:
- Research Overview: pools/research.md
- Supported Algorithms: pools/algorithms.md
- Stratum Protocol: pools/stratum.md
- Pool Configuration: pools/configuration.md
- ETChash Pools: pools/etchash.md
- ProgPowZ Pools: pools/progpowz.md
- Blake3DCR Pools: pools/blake3dcr.md
- Custom Pools: pools/custom.md
- Miners:
- Overview: miners/overview.md
- XMRig: miners/xmrig.md
- Adding New Miners: miners/adding-miners.md
- Troubleshooting:
- Common Issues: troubleshooting/common-issues.md
- Logs: troubleshooting/logs.md
- Performance: troubleshooting/performance.md
- GPU Issues: troubleshooting/gpu.md
- Network Issues: troubleshooting/network.md
- FAQ: faq.md
- Changelog: changelog.md
- License: license.md