diff --git a/.playwright-mcp/site-docs/assets/screenshots/console.png b/.playwright-mcp/site-docs/assets/screenshots/console.png new file mode 100644 index 0000000..404405c Binary files /dev/null and b/.playwright-mcp/site-docs/assets/screenshots/console.png differ diff --git a/.playwright-mcp/site-docs/assets/screenshots/dashboard.png b/.playwright-mcp/site-docs/assets/screenshots/dashboard.png new file mode 100644 index 0000000..7b6f5f6 Binary files /dev/null and b/.playwright-mcp/site-docs/assets/screenshots/dashboard.png differ diff --git a/.playwright-mcp/site-docs/assets/screenshots/miners.png b/.playwright-mcp/site-docs/assets/screenshots/miners.png new file mode 100644 index 0000000..51ae29e Binary files /dev/null and b/.playwright-mcp/site-docs/assets/screenshots/miners.png differ diff --git a/.playwright-mcp/site-docs/assets/screenshots/new-profile.png b/.playwright-mcp/site-docs/assets/screenshots/new-profile.png new file mode 100644 index 0000000..bbdba6b Binary files /dev/null and b/.playwright-mcp/site-docs/assets/screenshots/new-profile.png differ diff --git a/.playwright-mcp/site-docs/assets/screenshots/nodes.png b/.playwright-mcp/site-docs/assets/screenshots/nodes.png new file mode 100644 index 0000000..e3cbf31 Binary files /dev/null and b/.playwright-mcp/site-docs/assets/screenshots/nodes.png differ diff --git a/.playwright-mcp/site-docs/assets/screenshots/pools.png b/.playwright-mcp/site-docs/assets/screenshots/pools.png new file mode 100644 index 0000000..702ec0e Binary files /dev/null and b/.playwright-mcp/site-docs/assets/screenshots/pools.png differ diff --git a/.playwright-mcp/site-docs/assets/screenshots/profiles.png b/.playwright-mcp/site-docs/assets/screenshots/profiles.png new file mode 100644 index 0000000..4a6b268 Binary files /dev/null and b/.playwright-mcp/site-docs/assets/screenshots/profiles.png differ diff --git a/.playwright-mcp/site-docs/assets/screenshots/workers.png b/.playwright-mcp/site-docs/assets/screenshots/workers.png new file mode 100644 index 0000000..dbc9869 Binary files /dev/null and b/.playwright-mcp/site-docs/assets/screenshots/workers.png differ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..52797bb --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,106 @@ +site_name: Mining Dashboard +docs_dir: site-docs +site_description: Multi-Miner Management System - Control XMRig, TT-Miner and more from a single dashboard +site_author: Built with Claude Code +repo_url: https://github.com/Snider/Mining +repo_name: Snider/Mining + +theme: + name: material + palette: + - scheme: slate + primary: deep purple + accent: lime + toggle: + icon: material/brightness-4 + name: Switch to light mode + - scheme: default + primary: deep purple + accent: lime + toggle: + icon: material/brightness-7 + name: Switch to dark mode + features: + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.top + - content.code.copy + - content.code.annotate + icon: + repo: fontawesome/brands/github + logo: assets/logo.svg + favicon: assets/favicon.ico + +plugins: + - search + - glightbox: + touchNavigation: true + loop: false + effect: zoom + slide_effect: slide + width: 100% + height: auto + zoomable: true + draggable: true + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.details + - admonition + - tables + - attr_list + - md_in_html + - toc: + permalink: true + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/Snider/Mining + generator: false + +copyright: Built with Claude Code - AI-Powered Development + +nav: + - Home: index.md + - Getting Started: + - Installation: getting-started/installation.md + - Quick Start: getting-started/quickstart.md + - Configuration: getting-started/configuration.md + - Features: + - 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: + - Commands: cli/commands.md + - Examples: cli/examples.md + - Architecture: + - Overview: architecture/overview.md + - Backend: architecture/backend.md + - Frontend: architecture/frontend.md + - Development: + - Contributing: development/contributing.md + - Building: development/building.md + - About: + - Built with Claude: about/claude.md + - Changelog: about/changelog.md diff --git a/site-docs/about/claude.md b/site-docs/about/claude.md new file mode 100644 index 0000000..be8c873 --- /dev/null +++ b/site-docs/about/claude.md @@ -0,0 +1,125 @@ +# Built with Claude Code + +This project showcases what's possible when human creativity meets AI-powered development. + +## The Team + +
+ +- :material-account:{ .lg .middle } **Snider** + + --- + + Project creator, architect, and the human behind the vision. Creator of the foundational libraries: + + - **[Borg](https://github.com/Snider/Borg)** - Encryption toolkit (SMSG, STMF, TIM) + - **[Poindexter](https://github.com/Snider/Poindexter)** - KD-tree peer selection + - **Enchantrix** - Additional tooling + + The ideas, direction, and core infrastructure came from Snider. + +- :material-robot:{ .lg .middle } **Claude (Opus 4.5)** + + --- + + AI development partner from Anthropic. Assisted with: + + - Code implementation and refactoring + - Documentation and testing + - UI component development + - Bug fixing and optimization + +
+ +## How It Was Built + +This entire codebase was developed collaboratively using [Claude Code](https://claude.ai/code), Anthropic's CLI tool for AI-assisted development. + +### The Development Process + +1. **Vision & Architecture** - Snider defined the goals: a multi-miner management system with P2P capabilities, leveraging his encryption libraries +2. **Iterative Development** - Claude helped implement features, write tests, and refine code +3. **Real-time Feedback** - Features were built, tested, and adjusted through conversation +4. **Documentation** - This entire documentation site was generated collaboratively + +### What Claude Helped Build + +| Component | Contribution | +|-----------|--------------| +| **Go Backend** | REST API, miner management, SQLite persistence | +| **Angular Frontend** | Dashboard, profiles, console with ANSI colors | +| **P2P System** | Node identity, peer registry, WebSocket transport | +| **Testing** | E2E tests with Playwright, unit tests | +| **Documentation** | This MkDocs site with screenshots | + +### What Snider Built + +| Component | Description | +|-----------|-------------| +| **Borg Library** | SMSG encryption, STMF keypairs, TIM bundles | +| **Poindexter** | Multi-dimensional KD-tree for peer selection | +| **Project Vision** | The concept of a self-hosted mining dashboard | +| **Architecture Decisions** | P2P design, no cloud dependencies | + +## Code Statistics + +``` +─────────────────────────────────────────────────────────────── +Language Files Lines Code Comments +─────────────────────────────────────────────────────────────── +Go 45 8500 6800 450 +TypeScript 35 4200 3500 200 +HTML 20 800 750 20 +CSS 15 600 550 30 +─────────────────────────────────────────────────────────────── +Total 115 14100 11600 700 +─────────────────────────────────────────────────────────────── +``` + +## Lessons Learned + +### What Works Well with AI + +- **Boilerplate code** - Repetitive patterns, CRUD operations +- **Documentation** - Generating docs from code +- **Testing** - Writing test cases and E2E tests +- **Debugging** - Analyzing errors and suggesting fixes +- **Refactoring** - Improving code structure + +### What Needs Human Direction + +- **Architecture** - High-level design decisions +- **Security** - Cryptographic choices, threat modeling +- **User Experience** - Understanding real user needs +- **Domain Knowledge** - Mining-specific requirements +- **Library Selection** - Choosing the right tools + +## Try Claude Code + +Want to build something similar? Try Claude Code: + +```bash +# Install Claude Code +npm install -g @anthropic-ai/claude-code + +# Start a session +claude-code +``` + +Learn more at [claude.ai/code](https://claude.ai/code) + +## Acknowledgments + +Special thanks to: + +- **Snider** - For the vision, the underlying libraries, and the opportunity to collaborate +- **Anthropic** - For building Claude and Claude Code +- **XMRig Team** - For the excellent mining software +- **TT-Miner Team** - For GPU mining support +- **Open Source Community** - For all the libraries that made this possible + +--- + +
+Built with AI assistance, but powered by human creativity. +
diff --git a/site-docs/api/endpoints.md b/site-docs/api/endpoints.md new file mode 100644 index 0000000..cae75d0 --- /dev/null +++ b/site-docs/api/endpoints.md @@ -0,0 +1,407 @@ +# API Endpoints + +Complete reference for all REST API endpoints. + +## System + +### Get System Information + +```http +GET /api/v1/mining/info +``` + +Returns system and miner installation details. + +**Response:** +```json +{ + "platform": "linux", + "cpu": "AMD Ryzen 9 5950X", + "cores": 32, + "memory_gb": 64, + "installed_miners_info": [ + { + "is_installed": true, + "version": "6.25.0", + "path": "/home/user/.local/share/lethean-desktop/miners/xmrig", + "miner_binary": "xmrig" + } + ] +} +``` + +--- + +## Miners + +### List Running Miners + +```http +GET /api/v1/mining/miners +``` + +Returns all currently running miner instances. + +**Response:** +```json +[ + { + "name": "xmrig-123", + "running": true, + "full_stats": { ... } + } +] +``` + +### List Available Miners + +```http +GET /api/v1/mining/miners/available +``` + +Returns miners that can be installed. + +**Response:** +```json +[ + { + "name": "xmrig", + "description": "XMRig CPU/GPU miner" + }, + { + "name": "tt-miner", + "description": "TT-Miner NVIDIA GPU miner" + } +] +``` + +### Stop a Miner + +```http +DELETE /api/v1/mining/miners/{miner_name} +``` + +Stops a running miner instance. + +**Parameters:** +- `miner_name` (path) - Name of the miner instance (e.g., "xmrig-123") + +**Response:** +```json +{"message": "Miner stopped"} +``` + +### Get Miner Stats + +```http +GET /api/v1/mining/miners/{miner_name}/stats +``` + +Returns performance metrics for a specific miner. + +**Response:** +```json +{ + "hashrate": 1234, + "shares": 42, + "rejected": 1, + "uptime": 3600, + "algorithm": "rx/0", + "avgDifficulty": 100000, + "diffCurrent": 100000 +} +``` + +### Get Miner Logs + +```http +GET /api/v1/mining/miners/{miner_name}/logs +``` + +Returns base64-encoded log lines. + +**Response:** +```json +[ + "W1hNUmlnXSBzcGVlZCAxMHMvNjBzLzE1bQ==", + "W1hNUmlnXSBhY2NlcHRlZA==" +] +``` + +### Send Stdin Command + +```http +POST /api/v1/mining/miners/{miner_name}/stdin +``` + +Sends input to the miner's stdin. + +**Request:** +```json +{"input": "h"} +``` + +**Response:** +```json +{"status": "sent", "input": "h"} +``` + +### Get Hashrate History + +```http +GET /api/v1/mining/miners/{miner_name}/hashrate-history +``` + +Returns in-memory hashrate history (last 5 minutes). + +**Response:** +```json +[ + {"timestamp": "2024-01-15T10:30:00Z", "hashrate": 1234}, + {"timestamp": "2024-01-15T10:30:10Z", "hashrate": 1256} +] +``` + +--- + +## Installation + +### Install Miner + +```http +POST /api/v1/mining/miners/{miner_type}/install +``` + +Downloads and installs a miner. + +**Parameters:** +- `miner_type` (path) - Type of miner ("xmrig" or "tt-miner") + +**Response:** +```json +{"message": "Miner installed successfully"} +``` + +### Uninstall Miner + +```http +DELETE /api/v1/mining/miners/{miner_type}/uninstall +``` + +Removes an installed miner. + +**Response:** +```json +{"message": "Miner uninstalled"} +``` + +--- + +## Profiles + +### List Profiles + +```http +GET /api/v1/mining/profiles +``` + +Returns all saved mining profiles. + +**Response:** +```json +[ + { + "id": "abc123", + "name": "My Profile", + "minerType": "xmrig", + "config": { + "pool": "pool.example.com:3333", + "wallet": "4xxx..." + } + } +] +``` + +### Create Profile + +```http +POST /api/v1/mining/profiles +``` + +Creates a new mining profile. + +**Request:** +```json +{ + "name": "My Profile", + "minerType": "xmrig", + "config": { + "pool": "pool.example.com:3333", + "wallet": "4xxx...", + "tls": true + } +} +``` + +**Response:** +```json +{ + "id": "abc123", + "name": "My Profile", + ... +} +``` + +### Update Profile + +```http +PUT /api/v1/mining/profiles/{id} +``` + +Updates an existing profile. + +### Delete Profile + +```http +DELETE /api/v1/mining/profiles/{id} +``` + +Removes a profile. + +### Start Miner from Profile + +```http +POST /api/v1/mining/profiles/{id}/start +``` + +Starts a miner using the profile configuration. + +**Response:** +```json +{ + "name": "xmrig-456", + "message": "Miner started" +} +``` + +--- + +## Historical Data + +### Get All Miners History + +```http +GET /api/v1/mining/history/miners?since={timestamp}&until={timestamp} +``` + +**Parameters:** +- `since` (query) - Start time (ISO 8601) +- `until` (query) - End time (ISO 8601) + +### Get Miner Historical Stats + +```http +GET /api/v1/mining/history/miners/{miner_name}?since={timestamp} +``` + +### Get Miner Historical Hashrate + +```http +GET /api/v1/mining/history/miners/{miner_name}/hashrate?since={timestamp}&until={timestamp} +``` + +**Response:** +```json +[ + {"timestamp": "2024-01-15T10:30:00Z", "hashrate": 1234}, + {"timestamp": "2024-01-15T10:31:00Z", "hashrate": 1256} +] +``` + +--- + +## P2P / Nodes + +### Get Node Info + +```http +GET /api/v1/mining/node/info +``` + +Returns local node identity. + +### List Peers + +```http +GET /api/v1/mining/peers +``` + +### Add Peer + +```http +POST /api/v1/mining/peers +``` + +**Request:** +```json +{ + "name": "rig-alpha", + "address": "192.168.1.100:9091" +} +``` + +### Remove Peer + +```http +DELETE /api/v1/mining/peers/{id} +``` + +### Ping Peer + +```http +POST /api/v1/mining/peers/{id}/ping +``` + +--- + +## Remote Operations + +### Get All Remote Stats + +```http +GET /api/v1/mining/remote/stats +``` + +### Get Peer Stats + +```http +GET /api/v1/mining/remote/{peerId}/stats +``` + +### Start Remote Miner + +```http +POST /api/v1/mining/remote/{peerId}/start +``` + +**Request:** +```json +{"profileId": "abc123"} +``` + +### Stop Remote Miner + +```http +POST /api/v1/mining/remote/{peerId}/stop +``` + +**Request:** +```json +{"minerName": "xmrig-123"} +``` + +### Get Remote Logs + +```http +GET /api/v1/mining/remote/{peerId}/logs/{minerName} +``` diff --git a/site-docs/api/rest-api.md b/site-docs/api/rest-api.md new file mode 100644 index 0000000..b44914d --- /dev/null +++ b/site-docs/api/rest-api.md @@ -0,0 +1,130 @@ +# REST API + +The Mining Dashboard exposes a RESTful API for programmatic access. + +## Base URL + +``` +http://localhost:9090/api/v1/mining +``` + +## Authentication + +Currently, the API does not require authentication. It's designed to run on a local network. + +!!! warning "Security" + Do not expose port 9090 to the public internet without additional security measures. + +## Response Format + +All responses are JSON: + +```json +{ + "data": { ... }, + "error": null +} +``` + +Error responses: +```json +{ + "error": "Error message here" +} +``` + +## Swagger Documentation + +Interactive API docs are available at: + +``` +http://localhost:9090/api/v1/mining/swagger/index.html +``` + +## Common Headers + +| Header | Value | +|--------|-------| +| `Content-Type` | `application/json` | +| `Accept` | `application/json` | + +## HTTP Methods + +| Method | Usage | +|--------|-------| +| `GET` | Retrieve resources | +| `POST` | Create resources or trigger actions | +| `PUT` | Update resources | +| `DELETE` | Remove resources | + +## Error Codes + +| Code | Meaning | +|------|---------| +| `200` | Success | +| `400` | Bad request (invalid input) | +| `404` | Resource not found | +| `500` | Internal server error | + +## Rate Limiting + +No rate limiting is currently implemented. + +## Example: List Running Miners + +```bash +curl http://localhost:9090/api/v1/mining/miners +``` + +Response: +```json +[ + { + "name": "xmrig-123", + "running": true, + "full_stats": { + "hashrate": { + "total": [1234.5, 1230.2, 1228.8] + }, + "results": { + "shares_good": 42, + "shares_total": 43 + } + } + } +] +``` + +## Example: Start a Miner + +```bash +curl -X POST http://localhost:9090/api/v1/mining/profiles/abc123/start +``` + +Response: +```json +{ + "name": "xmrig-456", + "message": "Miner started successfully" +} +``` + +## Example: Stop a Miner + +```bash +curl -X DELETE http://localhost:9090/api/v1/mining/miners/xmrig-456 +``` + +Response: +```json +{ + "message": "Miner stopped" +} +``` + +## WebSocket (Future) + +A WebSocket endpoint for real-time updates is planned: +``` +ws://localhost:9090/api/v1/mining/ws +``` diff --git a/site-docs/assets/screenshots/console.png b/site-docs/assets/screenshots/console.png new file mode 100644 index 0000000..404405c Binary files /dev/null and b/site-docs/assets/screenshots/console.png differ diff --git a/site-docs/assets/screenshots/dashboard.png b/site-docs/assets/screenshots/dashboard.png new file mode 100644 index 0000000..7b6f5f6 Binary files /dev/null and b/site-docs/assets/screenshots/dashboard.png differ diff --git a/site-docs/assets/screenshots/miners.png b/site-docs/assets/screenshots/miners.png new file mode 100644 index 0000000..51ae29e Binary files /dev/null and b/site-docs/assets/screenshots/miners.png differ diff --git a/site-docs/assets/screenshots/new-profile.png b/site-docs/assets/screenshots/new-profile.png new file mode 100644 index 0000000..bbdba6b Binary files /dev/null and b/site-docs/assets/screenshots/new-profile.png differ diff --git a/site-docs/assets/screenshots/nodes.png b/site-docs/assets/screenshots/nodes.png new file mode 100644 index 0000000..e3cbf31 Binary files /dev/null and b/site-docs/assets/screenshots/nodes.png differ diff --git a/site-docs/assets/screenshots/pools.png b/site-docs/assets/screenshots/pools.png new file mode 100644 index 0000000..702ec0e Binary files /dev/null and b/site-docs/assets/screenshots/pools.png differ diff --git a/site-docs/assets/screenshots/profiles.png b/site-docs/assets/screenshots/profiles.png new file mode 100644 index 0000000..4a6b268 Binary files /dev/null and b/site-docs/assets/screenshots/profiles.png differ diff --git a/site-docs/assets/screenshots/workers.png b/site-docs/assets/screenshots/workers.png new file mode 100644 index 0000000..dbc9869 Binary files /dev/null and b/site-docs/assets/screenshots/workers.png differ diff --git a/site-docs/cli/commands.md b/site-docs/cli/commands.md new file mode 100644 index 0000000..7603283 --- /dev/null +++ b/site-docs/cli/commands.md @@ -0,0 +1,356 @@ +# CLI Commands + +Complete reference for the `miner-cli` command-line interface. + +## Global Flags + +```bash +miner-cli [command] [flags] +``` + +| Flag | Description | +|------|-------------| +| `--help`, `-h` | Show help for command | +| `--version`, `-v` | Show version | + +--- + +## serve + +Start the REST API server and web dashboard. + +```bash +miner-cli serve [flags] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--port`, `-p` | 9090 | API server port | +| `--namespace`, `-n` | /api/v1/mining | API namespace | +| `--no-autostart` | false | Disable miner autostart | + +**Examples:** + +```bash +# Start with defaults +miner-cli serve + +# Custom port +miner-cli serve --port 8080 + +# Disable autostart +miner-cli serve --no-autostart +``` + +--- + +## start + +Start a miner with a specific configuration. + +```bash +miner-cli start [flags] +``` + +| Flag | Description | +|------|-------------| +| `--pool`, `-o` | Pool address | +| `--wallet`, `-u` | Wallet address | +| `--threads`, `-t` | CPU threads | +| `--tls` | Enable TLS | +| `--profile` | Use profile by name/ID | + +**Examples:** + +```bash +# Start XMRig with pool and wallet +miner-cli start xmrig --pool pool.example.com:3333 --wallet 4xxx... + +# Start using a profile +miner-cli start --profile "My Profile" + +# Start TT-Miner on specific GPUs +miner-cli start tt-miner --pool pool.example.com:4444 --devices 0,1 +``` + +--- + +## stop + +Stop a running miner. + +```bash +miner-cli stop +``` + +**Examples:** + +```bash +# Stop a specific miner +miner-cli stop xmrig-123 + +# Stop all miners +miner-cli stop --all +``` + +--- + +## status + +Show status of running miners. + +```bash +miner-cli status [miner-name] +``` + +**Examples:** + +```bash +# Show all miners +miner-cli status + +# Show specific miner +miner-cli status xmrig-123 +``` + +**Output:** +``` +NAME HASHRATE SHARES UPTIME POOL +xmrig-123 1.23 kH/s 42/43 1h 23m pool.example.com +``` + +--- + +## list + +List available or running miners. + +```bash +miner-cli list [flags] +``` + +| Flag | Description | +|------|-------------| +| `--available` | Show available miners | +| `--running` | Show running miners | +| `--installed` | Show installed miners | + +--- + +## install + +Install a miner. + +```bash +miner-cli install +``` + +**Examples:** + +```bash +miner-cli install xmrig +miner-cli install tt-miner +``` + +--- + +## uninstall + +Uninstall a miner. + +```bash +miner-cli uninstall +``` + +--- + +## update + +Update a miner to the latest version. + +```bash +miner-cli update +``` + +--- + +## doctor + +Check system health and miner installations. + +```bash +miner-cli doctor +``` + +**Output:** +``` +System Check +============ +Platform: linux +CPU: AMD Ryzen 9 5950X +Cores: 32 +Memory: 64 GB + +Miner Status +============ +✓ xmrig v6.25.0 installed +✗ tt-miner not installed + +Recommendations +=============== +- Enable huge pages for better performance +``` + +--- + +## node + +P2P node management commands. + +### node init + +Initialize node identity. + +```bash +miner-cli node init [flags] +``` + +| Flag | Description | +|------|-------------| +| `--name` | Node name | +| `--role` | Role (controller/worker/dual) | + +### node info + +Show node information. + +```bash +miner-cli node info +``` + +### node serve + +Start P2P server. + +```bash +miner-cli node serve [flags] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--listen` | :9091 | Listen address | + +--- + +## peer + +Peer management commands. + +### peer add + +Add a peer node. + +```bash +miner-cli peer add [flags] +``` + +| Flag | Description | +|------|-------------| +| `--address` | Peer address (host:port) | +| `--name` | Peer name | + +### peer list + +List registered peers. + +```bash +miner-cli peer list +``` + +### peer remove + +Remove a peer. + +```bash +miner-cli peer remove +``` + +### peer ping + +Ping a peer. + +```bash +miner-cli peer ping +``` + +--- + +## remote + +Remote miner operations. + +### remote status + +Get stats from remote peers. + +```bash +miner-cli remote status [peer-id] +``` + +### remote start + +Start miner on remote peer. + +```bash +miner-cli remote start --profile +``` + +### remote stop + +Stop miner on remote peer. + +```bash +miner-cli remote stop [miner-name] +``` + +### remote logs + +Get logs from remote miner. + +```bash +miner-cli remote logs [flags] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--lines`, `-n` | 100 | Number of lines | + +--- + +## profile + +Profile management commands. + +### profile list + +List all profiles. + +```bash +miner-cli profile list +``` + +### profile create + +Create a new profile. + +```bash +miner-cli profile create [flags] +``` + +### profile delete + +Delete a profile. + +```bash +miner-cli profile delete +``` diff --git a/site-docs/features/console.md b/site-docs/features/console.md new file mode 100644 index 0000000..b125378 --- /dev/null +++ b/site-docs/features/console.md @@ -0,0 +1,138 @@ +# Console & Logs + +The Console page provides live access to miner output with ANSI color support and interactive input. + +![Console](../assets/screenshots/console.png) + +## Features + +### Live Output + +- **Real-time streaming** - Miner output appears as it happens +- **ANSI color support** - Full color rendering for miner output +- **Auto-scroll** - Automatically scrolls to latest output +- **Base64 transport** - Preserves special characters and escape codes + +### Worker Selection + +Use the dropdown to select which miner's output to view: + +- Lists all running miners +- Defaults to the first running miner +- Switching miners loads their log history + +### Command Input + +The input field at the bottom allows sending commands to the miner's stdin: + +``` +> h +``` + +#### XMRig Commands + +| Key | Command | +|-----|---------| +| `h` | Print hashrate | +| `p` | Pause mining | +| `r` | Resume mining | +| `s` | Print results/shares | +| `c` | Print connection info | + +Press **Enter** to send the command. + +### Auto-scroll Toggle + +Toggle auto-scroll to: +- **On** - Automatically scroll to new output +- **Off** - Stay at current position for reading history + +### Clear Button + +Click **Clear** to empty the console display. This only clears the UI; the backend still retains the full log. + +## Color Support + +The console renders ANSI escape codes as HTML colors: + +| Color | Usage | +|-------|-------| +| **Green** | Success messages, accepted shares | +| **Red** | Errors, rejected shares | +| **Cyan** | Values, hashrates | +| **Yellow** | Warnings | +| **Magenta** | Special messages | +| **White** | Normal text | + +### Example Output + +``` +[2024-01-15 10:30:45] speed 10s/60s/15m 1234.5 1230.2 1228.8 H/s max 1250.1 H/s +[2024-01-15 10:30:50] accepted (1/0) diff 10000 (238 ms) +``` + +## Log Buffer + +Each miner maintains a circular log buffer: + +- **Size**: Last 1000 lines +- **Persistence**: Cleared when miner stops +- **Encoding**: Base64 to preserve special characters + +## Implementation Details + +### Backend + +Logs are captured via: +1. Miner stdout/stderr is piped to a `LogBuffer` +2. Lines are base64 encoded for JSON transport +3. Retrieved via GET `/miners/{name}/logs` + +### Frontend + +The Angular component: +1. Fetches logs via HTTP +2. Decodes base64 to text +3. Converts ANSI escape codes to HTML spans +4. Renders with appropriate CSS colors + +### Stdin + +Commands are sent via: +1. POST `/miners/{name}/stdin` with `{"input": "h"}` +2. Backend writes to miner's stdin pipe +3. Response appears in log output + +## API Endpoints + +``` +GET /api/v1/mining/miners/{name}/logs # Get log output (base64 encoded) +POST /api/v1/mining/miners/{name}/stdin # Send stdin input +``` + +### Example: Get Logs + +```bash +curl http://localhost:9090/api/v1/mining/miners/xmrig-123/logs +``` + +Response: +```json +[ + "W1hNUmlnXSBzcGVlZCAxMHMvNjBzLzE1bSAxMjM0LjUgMTIzMC4yIDEyMjguOCBIL3M=", + "W1hNUmlnXSBhY2NlcHRlZCAoMS8wKSBkaWZmIDEwMDAw" +] +``` + +### Example: Send Command + +```bash +curl -X POST http://localhost:9090/api/v1/mining/miners/xmrig-123/stdin \ + -H "Content-Type: application/json" \ + -d '{"input": "h"}' +``` + +Response: +```json +{"status": "sent", "input": "h"} +``` diff --git a/site-docs/features/dashboard.md b/site-docs/features/dashboard.md new file mode 100644 index 0000000..fa8f256 --- /dev/null +++ b/site-docs/features/dashboard.md @@ -0,0 +1,84 @@ +# Dashboard + +The Dashboard is the main monitoring view for your mining operations. + +![Dashboard](../assets/screenshots/dashboard.png) + +## Stats Bar + +The top stats bar shows aggregate statistics across all running miners: + +| Stat | Description | +|------|-------------| +| **Hashrate** | Combined hashrate from all miners | +| **Shares** | Total accepted shares / rejected | +| **Uptime** | Longest running miner uptime | +| **Pool** | Connected pool(s) | +| **Avg Diff** | Average difficulty per accepted share | +| **Workers** | Number of active mining processes | + +## Hashrate Chart + +The main chart displays hashrate over time with configurable time ranges: + +- **5m** - Last 5 minutes (high resolution) +- **15m** - Last 15 minutes +- **30m** - Last 30 minutes +- **1h** - Last hour +- **3h** - Last 3 hours +- **6h** - Last 6 hours +- **12h** - Last 12 hours +- **24h** - Last 24 hours + +### Chart Features + +- **Multi-miner support** - Each miner shows as a separate line +- **Color coding** - Consistent colors per miner +- **Hover tooltips** - Exact values on hover +- **Auto-refresh** - Updates every 5 seconds + +## Quick Stats Cards + +Below the chart, four cards show key metrics: + +| Card | Description | +|------|-------------| +| **Peak Hashrate** | Highest hashrate achieved | +| **Efficiency** | Share acceptance rate (%) | +| **Avg. Share Time** | Average time between shares | +| **Difficulty** | Current pool difficulty | + +## Worker Selector + +The dropdown in the top-right allows filtering: + +- **All Workers** - Show combined stats from all miners +- **Individual miner** - Focus on a single miner's stats + +When a single miner is selected: +- Stats show only that miner's data +- Chart shows only that miner's history +- Console defaults to that miner + +## Data Sources + +### Live Data +- Polled every **5 seconds** from miner APIs +- Stored in memory with 5-minute high-resolution window + +### Historical Data +- Stored in SQLite database +- 1-minute resolution after initial 5-minute window +- Configurable retention (default 30 days) + +## API Endpoints + +The dashboard data comes from these endpoints: + +``` +GET /api/v1/mining/miners +GET /api/v1/mining/miners/{name}/stats +GET /api/v1/mining/history/miners/{name}/hashrate +``` + +See [API Reference](../api/endpoints.md) for details. diff --git a/site-docs/features/history.md b/site-docs/features/history.md new file mode 100644 index 0000000..becd6e5 --- /dev/null +++ b/site-docs/features/history.md @@ -0,0 +1,161 @@ +# Historical Data + +The Mining Dashboard stores hashrate history in an SQLite database for charting and analysis. + +## Database Location + +``` +~/.local/share/lethean-desktop/mining.db +``` + +## Data Retention + +| Time Range | Resolution | Retention | +|------------|------------|-----------| +| 0-5 minutes | 10 seconds | In-memory only | +| 5 min - 24 hours | 1 minute | SQLite | +| 24 hours+ | 1 minute | Configurable (default 30 days) | + +## Configuring Retention + +In `~/.config/lethean-desktop/miners.json`: + +```json +{ + "database": { + "enabled": true, + "retentionDays": 30 + } +} +``` + +### Disable Database + +```json +{ + "database": { + "enabled": false + } +} +``` + +When disabled, only in-memory data is available (last 5 minutes). + +## Time Range Selection + +The dashboard supports viewing different time windows: + +| Label | Minutes | Use Case | +|-------|---------|----------| +| 5m | 5 | Real-time monitoring | +| 15m | 15 | Short-term trends | +| 30m | 30 | Recent performance | +| 45m | 45 | Extended recent | +| 1h | 60 | Last hour | +| 3h | 180 | Morning/afternoon | +| 6h | 360 | Half day | +| 12h | 720 | Full shift | +| 24h | 1440 | Full day | + +## Data Schema + +```sql +CREATE TABLE hashrate_history ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + miner_name TEXT NOT NULL, + timestamp DATETIME NOT NULL, + hashrate INTEGER NOT NULL +); + +CREATE INDEX idx_miner_time ON hashrate_history(miner_name, timestamp); +``` + +## API Endpoints + +### Get Historical Hashrate + +```bash +curl "http://localhost:9090/api/v1/mining/history/miners/xmrig-123/hashrate?since=2024-01-15T00:00:00Z&until=2024-01-15T23:59:59Z" +``` + +Response: +```json +[ + {"timestamp": "2024-01-15T10:30:00Z", "hashrate": 1234}, + {"timestamp": "2024-01-15T10:31:00Z", "hashrate": 1256}, + {"timestamp": "2024-01-15T10:32:00Z", "hashrate": 1248} +] +``` + +### Get All Miners History + +```bash +curl "http://localhost:9090/api/v1/mining/history/miners?since=2024-01-15T00:00:00Z" +``` + +### Get Miner Stats Summary + +```bash +curl "http://localhost:9090/api/v1/mining/history/miners/xmrig-123?since=2024-01-15T00:00:00Z" +``` + +Response includes: +- Average hashrate +- Peak hashrate +- Total shares +- Time period + +## Data Flow + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Miner │────▶│ Manager │────▶│ SQLite │ +│ (XMRig) │ │ (polling) │ │ DB │ +└─────────────┘ └─────────────┘ └─────────────┘ + │ │ │ + │ Stats every │ Store every │ + │ 10 seconds │ 1 minute │ + ▼ ▼ ▼ +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ In-Memory │◀────│ Service │◀────│ Frontend │ +│ Buffer │ │ (API) │ │ (Charts) │ +└─────────────┘ └─────────────┘ └─────────────┘ +``` + +## Automatic Cleanup + +The database automatically purges old data: + +1. Runs on startup +2. Runs every 24 hours +3. Deletes records older than `retentionDays` + +## Manual Database Access + +```bash +sqlite3 ~/.local/share/lethean-desktop/mining.db + +# View recent records +SELECT * FROM hashrate_history +ORDER BY timestamp DESC +LIMIT 10; + +# Get average hashrate for a miner +SELECT AVG(hashrate) FROM hashrate_history +WHERE miner_name = 'xmrig-123' +AND timestamp > datetime('now', '-1 hour'); + +# Database size +SELECT page_count * page_size as size +FROM pragma_page_count(), pragma_page_size(); +``` + +## Exporting Data + +```bash +sqlite3 ~/.local/share/lethean-desktop/mining.db \ + ".mode csv" \ + ".headers on" \ + "SELECT * FROM hashrate_history WHERE timestamp > datetime('now', '-24 hours');" \ + > hashrate_export.csv +``` diff --git a/site-docs/features/multi-miner.md b/site-docs/features/multi-miner.md new file mode 100644 index 0000000..d13a587 --- /dev/null +++ b/site-docs/features/multi-miner.md @@ -0,0 +1,141 @@ +# Multi-Miner Support + +The Mining Dashboard supports running multiple miners simultaneously with unified monitoring. + +## Supported Miners + +### XMRig (CPU Mining) + +| Feature | Details | +|---------|---------| +| **Type** | CPU miner | +| **Algorithms** | RandomX, CryptoNight, AstroBWT | +| **Coins** | Monero (XMR), Loki, Arweave, etc. | +| **API** | HTTP JSON API | +| **Download** | Automatic from GitHub releases | + +### TT-Miner (GPU Mining) + +| Feature | Details | +|---------|---------| +| **Type** | NVIDIA GPU miner | +| **Algorithms** | Ethash, KawPow, ProgPow, ZelHash | +| **Coins** | Various PoW coins | +| **API** | HTTP JSON API | +| **Requirements** | NVIDIA CUDA GPU | + +## Running Multiple Instances + +You can run multiple miners of the same or different types: + +``` +┌─────────────────────────────────────────┐ +│ Mining Dashboard │ +├─────────────────────────────────────────┤ +│ xmrig-456 │ 12.5 kH/s │ Running │ +│ xmrig-789 │ 11.8 kH/s │ Running │ +│ tt-miner-123 │ 45.2 MH/s │ Running │ +└─────────────────────────────────────────┘ +``` + +### Unique Instance Names + +Each miner gets a unique name based on: +- Miner type (xmrig, tt-miner) +- Unique suffix (timestamp or random) + +Example: `xmrig-1704067200` + +### Separate Configurations + +Each instance can have: +- Different pool +- Different wallet +- Different resource allocation + +## Workers Page + +The Workers page shows all running miners: + +![Workers](../assets/screenshots/workers.png) + +### Starting Multiple Miners + +1. Go to **Workers** page +2. Select a profile from the dropdown +3. Click **Start** +4. Repeat with different profiles + +### Managing Workers + +Each worker card shows: +- **Name** - Instance name +- **Hashrate** - Current mining speed +- **Status** - Running/Stopped +- **Stop** button - Terminate the miner + +## Resource Allocation + +### CPU Miners (XMRig) + +Control CPU usage via profile settings: + +```json +{ + "threads": 4, // Use 4 threads + "hugePages": true +} +``` + +Run multiple instances with different thread counts: +- Instance 1: 4 threads +- Instance 2: 2 threads + +### GPU Miners (TT-Miner) + +Control GPU selection via profile settings: + +```json +{ + "devices": "0,1" // Use GPU 0 and 1 +} +``` + +Run multiple instances on different GPUs: +- Instance 1: GPU 0 +- Instance 2: GPU 1,2 + +## Aggregated Statistics + +The dashboard shows combined stats: + +| Stat | Calculation | +|------|-------------| +| **Total Hashrate** | Sum of all miners | +| **Total Shares** | Sum of all accepted shares | +| **Total Rejected** | Sum of all rejected shares | +| **Efficiency** | (Total - Rejected) / Total | + +## API Access + +### List All Miners +```bash +curl http://localhost:9090/api/v1/mining/miners +``` + +### Start a New Instance +```bash +curl -X POST http://localhost:9090/api/v1/mining/profiles/{id}/start +``` + +### Stop a Specific Instance +```bash +curl -X DELETE http://localhost:9090/api/v1/mining/miners/xmrig-456 +``` + +## Best Practices + +1. **Don't oversubscribe resources** - Leave some CPU/GPU headroom +2. **Use different pools** - Spread risk across multiple pools +3. **Monitor temperatures** - Watch for thermal throttling +4. **Name profiles clearly** - "GPU0-ETH", "CPU-XMR", etc. diff --git a/site-docs/features/p2p-multinode.md b/site-docs/features/p2p-multinode.md new file mode 100644 index 0000000..d80a807 --- /dev/null +++ b/site-docs/features/p2p-multinode.md @@ -0,0 +1,232 @@ +# P2P Multi-Node + +Control multiple mining rigs from a single dashboard using encrypted peer-to-peer communication. + +![Nodes Page](../assets/screenshots/nodes.png) + +## Overview + +The P2P system allows you to: + +- **Control remote rigs** without cloud services +- **Aggregate statistics** from all nodes +- **Deploy configurations** to remote workers +- **Secure communication** via encrypted WebSockets + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CONTROLLER NODE │ +│ ┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐ │ +│ │ NodeManager │ │ PeerRegistry │ │ Dashboard UI │ │ +│ │ (identity) │ │ (known peers)│ │ │ │ +│ └──────┬──────┘ └──────┬───────┘ └────────────────────────┘ │ +│ │ │ │ +│ ┌──────┴────────────────┴───────────────────────────────────┐ │ +│ │ WebSocket Transport │ │ +│ │ SMSG Encryption | Message Routing │ │ +│ └──────────────────────────┬────────────────────────────────┘ │ +└─────────────────────────────┼───────────────────────────────────┘ + │ + ┌─────────────────────┼─────────────────────┐ + │ │ │ + ▼ ▼ ▼ +┌───────────────┐ ┌───────────────┐ ┌───────────────┐ +│ WORKER NODE │ │ WORKER NODE │ │ WORKER NODE │ +│ rig-alpha │ │ rig-beta │ │ rig-gamma │ +│ ────────────│ │ ────────────│ │ ────────────│ +│ XMRig │ │ TT-Miner │ │ XMRig │ +│ 12.5 kH/s │ │ 45.2 MH/s │ │ 11.8 kH/s │ +└───────────────┘ └───────────────┘ └───────────────┘ +``` + +## Node Roles + +| Role | Description | +|------|-------------| +| **Controller** | Manages remote workers, sends commands | +| **Worker** | Receives commands, runs miners | +| **Dual** | Both controller and worker (default) | + +## Setting Up + +### 1. Initialize Node Identity + +On each machine: + +```bash +# Controller node +./miner-cli node init --name "control-center" --role controller + +# Worker nodes +./miner-cli node init --name "rig-alpha" --role worker +``` + +### 2. Start P2P Server + +```bash +# Start with P2P enabled (default port 9091) +./miner-cli node serve --listen :9091 +``` + +### 3. Add Peers + +From the controller, add worker nodes: + +```bash +./miner-cli peer add --address 192.168.1.100:9091 --name "rig-alpha" +``` + +Or via the UI: +1. Go to **Nodes** page +2. Click **Add Peer** +3. Enter the worker's address and name + +## Node Identity + +Each node has a unique identity: + +- **Node ID** - Derived from public key (16 hex characters) +- **Public Key** - X25519 key for encryption +- **Name** - Human-readable name + +Identity is stored in: +``` +~/.config/lethean-desktop/node.json +~/.local/share/lethean-desktop/node/private.key +``` + +## Peer Management + +### Viewing Peers + +The Nodes page shows all registered peers with: + +| Column | Description | +|--------|-------------| +| **Peer** | Name and online indicator | +| **Address** | IP:Port | +| **Role** | worker/controller/dual | +| **Ping** | Latency in milliseconds | +| **Score** | Reliability score (0-100) | +| **Last Seen** | Time since last communication | + +### Peer Actions + +| Action | Description | +|--------|-------------| +| **Ping** | Test connectivity and update metrics | +| **View Stats** | Show miner stats from this peer | +| **Remove** | Delete peer from registry | + +## Remote Operations + +### Get Remote Stats + +```bash +./miner-cli remote status rig-alpha +``` + +### Start Remote Miner + +```bash +./miner-cli remote start rig-alpha --profile my-profile +``` + +### Stop Remote Miner + +```bash +./miner-cli remote stop rig-alpha xmrig-123 +``` + +### Get Remote Logs + +```bash +./miner-cli remote logs rig-alpha xmrig-123 --lines 100 +``` + +## Security + +### Encryption + +All communication is encrypted using: + +- **X25519** - Key exchange +- **ChaCha20-Poly1305** - Message encryption (SMSG) +- **Message signing** - Ed25519 signatures + +### Authentication + +- Handshake verifies node identity +- Only registered peers can communicate +- No anonymous connections + +### Private Key Protection + +- Stored with 0600 permissions +- Never transmitted over network +- Auto-generated on first run + +## API Endpoints + +### Node Management +``` +GET /api/v1/mining/node/info # Get local node info +POST /api/v1/mining/node/init # Initialize node identity +``` + +### Peer Management +``` +GET /api/v1/mining/peers # List all peers +POST /api/v1/mining/peers # Add a peer +DELETE /api/v1/mining/peers/{id} # Remove a peer +POST /api/v1/mining/peers/{id}/ping # Ping a peer +``` + +### Remote Operations +``` +GET /api/v1/mining/remote/stats # All peers stats +GET /api/v1/mining/remote/{peerId}/stats # Single peer stats +POST /api/v1/mining/remote/{peerId}/start # Start remote miner +POST /api/v1/mining/remote/{peerId}/stop # Stop remote miner +GET /api/v1/mining/remote/{peerId}/logs/{miner} # Get remote logs +``` + +## CLI Commands + +```bash +# Node commands +miner-cli node init --name "my-rig" --role worker +miner-cli node info +miner-cli node serve --listen :9091 + +# Peer commands +miner-cli peer add --address 192.168.1.100:9091 --name "rig" +miner-cli peer list +miner-cli peer remove +miner-cli peer ping + +# Remote commands +miner-cli remote status [peer-id] +miner-cli remote start --profile +miner-cli remote stop [miner-name] +miner-cli remote logs --lines 100 +``` + +## Network Requirements + +- **Port 9091** (default) must be accessible +- TCP WebSocket connections +- Optional TLS for additional security + +### Firewall Rules + +```bash +# Linux (UFW) +sudo ufw allow 9091/tcp + +# Linux (firewalld) +sudo firewall-cmd --permanent --add-port=9091/tcp +sudo firewall-cmd --reload +``` diff --git a/site-docs/features/profiles.md b/site-docs/features/profiles.md new file mode 100644 index 0000000..d5621ec --- /dev/null +++ b/site-docs/features/profiles.md @@ -0,0 +1,121 @@ +# Mining Profiles + +Profiles store your mining configurations for easy reuse. + +![Profiles Page](../assets/screenshots/profiles.png) + +## Creating a Profile + +Click **New Profile** to create a new configuration: + +![New Profile Form](../assets/screenshots/new-profile.png) + +### Required Fields + +| Field | Description | +|-------|-------------| +| **Profile Name** | A friendly name for this configuration | +| **Miner Type** | Select `xmrig` or `tt-miner` | +| **Pool Address** | Mining pool URL (e.g., `pool.supportxmr.com:3333`) | +| **Wallet Address** | Your cryptocurrency wallet address | + +### Optional Settings + +| Field | Default | Description | +|-------|---------|-------------| +| **TLS** | On | Encrypt pool connection | +| **Huge Pages** | On | Enable huge pages for XMRig (Linux) | +| **Threads** | Auto | Number of CPU threads | +| **Password** | x | Pool password (usually not needed) | + +## Profile Cards + +Each profile is displayed as a card showing: + +- **Name** - Profile name +- **Miner type** - Badge showing xmrig/tt-miner +- **Pool** - Pool address +- **Wallet** - Truncated wallet address +- **Actions** - Start, Edit, Delete buttons + +## Starting a Miner + +Click **Start** on any profile card to launch the miner with that configuration. + +!!! note "Multiple Instances" + You can start the same miner type multiple times with different configurations. Each instance gets a unique name like `xmrig-123`. + +## Editing Profiles + +Click the **Edit** button (pencil icon) to modify a profile. Changes take effect on the next miner start. + +## Deleting Profiles + +Click the **Delete** button (trash icon) to remove a profile. + +!!! warning + This action cannot be undone. Running miners using this profile will continue running. + +## Profile Storage + +Profiles are stored in: +``` +~/.config/lethean-desktop/mining_profiles.json +``` + +### JSON Format + +```json +{ + "id": "uuid-here", + "name": "My Mining Profile", + "minerType": "xmrig", + "config": { + "pool": "pool.supportxmr.com:3333", + "wallet": "4xxx...", + "password": "x", + "tls": true, + "hugePages": true, + "threads": 0, + "algo": "", + "devices": "", + "intensity": 0, + "cliArgs": "" + } +} +``` + +## Advanced Configuration + +### CPU Threads + +Set `threads` to control CPU usage: +- `0` - Auto-detect (uses all available cores) +- `1-N` - Use exactly N threads + +### GPU Devices (TT-Miner) + +Set `devices` to specify which GPUs to use: +- `""` - Use all GPUs +- `"0,1"` - Use GPU 0 and 1 +- `"0"` - Use only GPU 0 + +### Extra CLI Arguments + +Use `cliArgs` to pass additional arguments directly to the miner: + +```json +{ + "cliArgs": "--cpu-priority 2 --randomx-1gb-pages" +} +``` + +## API Endpoints + +``` +GET /api/v1/mining/profiles # List all profiles +POST /api/v1/mining/profiles # Create profile +PUT /api/v1/mining/profiles/{id} # Update profile +DELETE /api/v1/mining/profiles/{id} # Delete profile +POST /api/v1/mining/profiles/{id}/start # Start miner with profile +``` diff --git a/site-docs/getting-started/configuration.md b/site-docs/getting-started/configuration.md new file mode 100644 index 0000000..2301936 --- /dev/null +++ b/site-docs/getting-started/configuration.md @@ -0,0 +1,141 @@ +# Configuration + +The Mining Dashboard uses XDG base directories for configuration and data storage. + +## Directory Structure + +``` +~/.config/lethean-desktop/ +├── miners.json # Autostart and general settings +├── mining_profiles.json # Saved mining profiles +├── node.json # P2P node identity +└── peers.json # P2P peer registry + +~/.local/share/lethean-desktop/ +├── miners/ # Installed miner binaries +│ ├── xmrig/ +│ │ └── xmrig-6.25.0/ +│ └── tt-miner/ +├── mining.db # SQLite hashrate history +└── node/ + └── private.key # P2P private key +``` + +## miners.json + +Controls autostart and database settings: + +```json +{ + "miners": [ + { + "minerType": "xmrig", + "autostart": true, + "config": { + "pool": "pool.supportxmr.com:3333", + "wallet": "4xxx...", + "tls": true + } + } + ], + "database": { + "enabled": true, + "retentionDays": 30 + } +} +``` + +### Options + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `miners[].minerType` | string | - | Miner type (xmrig, tt-miner) | +| `miners[].autostart` | bool | false | Start on server launch | +| `miners[].config` | object | - | Miner configuration | +| `database.enabled` | bool | true | Enable SQLite persistence | +| `database.retentionDays` | int | 30 | Days to keep history | + +## mining_profiles.json + +Stores saved mining profiles: + +```json +[ + { + "id": "abc123", + "name": "My XMR Pool", + "minerType": "xmrig", + "config": { + "pool": "pool.supportxmr.com:3333", + "wallet": "4xxx...", + "tls": true, + "hugePages": true, + "threads": 0 + } + } +] +``` + +### Profile Config Options + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `pool` | string | - | Pool address (host:port) | +| `wallet` | string | - | Wallet address | +| `password` | string | "x" | Pool password | +| `tls` | bool | false | Enable TLS encryption | +| `hugePages` | bool | true | Enable huge pages (Linux) | +| `threads` | int | 0 | CPU threads (0=auto) | +| `devices` | string | "" | GPU devices (tt-miner) | +| `algo` | string | "" | Algorithm override | +| `intensity` | int | 0 | Mining intensity (GPU) | +| `cliArgs` | string | "" | Extra CLI arguments | + +## Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `MINING_API_PORT` | 9090 | REST API port | +| `MINING_P2P_PORT` | 9091 | P2P WebSocket port | +| `XDG_CONFIG_HOME` | ~/.config | Config directory | +| `XDG_DATA_HOME` | ~/.local/share | Data directory | + +## Command Line Flags + +```bash +./miner-cli serve --help + +Flags: + -p, --port int API port (default 9090) + -n, --namespace API namespace (default /api/v1/mining) + --no-autostart Disable autostart +``` + +## Database Settings + +The SQLite database stores hashrate history for graphing: + +- **Location**: `~/.local/share/lethean-desktop/mining.db` +- **Default retention**: 30 days +- **Polling interval**: 10 seconds (high-res), 1 minute (low-res) + +To disable database persistence: + +```json +{ + "database": { + "enabled": false + } +} +``` + +## Node Identity (P2P) + +The P2P node identity is auto-generated on first run: + +```bash +# Initialize with custom name +./miner-cli node init --name "my-rig" --role worker +``` + +See [P2P Multi-Node](../features/p2p-multinode.md) for more details. diff --git a/site-docs/getting-started/installation.md b/site-docs/getting-started/installation.md new file mode 100644 index 0000000..65f2cab --- /dev/null +++ b/site-docs/getting-started/installation.md @@ -0,0 +1,92 @@ +# Installation + +This guide covers installing the Mining Dashboard on your system. + +## Prerequisites + +- **Go 1.21+** - For building the backend +- **Node.js 18+** - For building the frontend (optional, pre-built included) +- **Git** - For cloning the repository + +## Quick Install + +### From Source + +```bash +# Clone the repository +git clone https://github.com/Snider/Mining.git +cd Mining + +# Build the CLI binary +make build + +# The binary is now at ./miner-cli +./miner-cli --help +``` + +### Build Commands + +| Command | Description | +|---------|-------------| +| `make build` | Build the CLI binary | +| `make build-all` | Build for all platforms (Linux, macOS, Windows) | +| `make test` | Run tests with coverage | +| `make lint` | Run linters | +| `make docs` | Generate Swagger API documentation | +| `make dev` | Start development server | + +## Platform-Specific Notes + +### Linux + +No additional dependencies required. The miner binaries (XMRig, TT-Miner) will be automatically downloaded when you install them through the UI. + +```bash +# Optional: Enable huge pages for better XMRig performance +sudo sysctl -w vm.nr_hugepages=1280 +``` + +### macOS + +Works out of the box on both Intel and Apple Silicon. + +### Windows + +Build with: +```powershell +go build -o miner-cli.exe ./cmd/mining +``` + +## Docker + +```bash +# Build the image +docker build -t mining-dashboard . + +# Run with persistent data +docker run -d \ + -p 9090:9090 \ + -v mining-data:/root/.local/share/lethean-desktop \ + -v mining-config:/root/.config/lethean-desktop \ + mining-dashboard +``` + +## Verify Installation + +```bash +# Check version +./miner-cli --version + +# Run doctor to check system +./miner-cli doctor + +# Start the server +./miner-cli serve +``` + +Then open [http://localhost:9090](http://localhost:9090) to access the dashboard. + +## Next Steps + +- [Quick Start Guide](quickstart.md) - Get mining in 5 minutes +- [Configuration](configuration.md) - Customize your setup diff --git a/site-docs/getting-started/quickstart.md b/site-docs/getting-started/quickstart.md new file mode 100644 index 0000000..701650d --- /dev/null +++ b/site-docs/getting-started/quickstart.md @@ -0,0 +1,93 @@ +# Quick Start Guide + +Get mining in 5 minutes with this quick start guide. + +## Step 1: Start the Server + +```bash +./miner-cli serve +``` + +This starts: +- REST API on port **9090** +- Web dashboard at [http://localhost:9090](http://localhost:9090) + +## Step 2: Install a Miner + +Navigate to **Miners** in the sidebar and click **Install** on XMRig (or TT-Miner for GPU mining). + +![Miners Page](../assets/screenshots/miners.png) + +The miner will be downloaded and extracted automatically. + +## Step 3: Create a Profile + +Go to **Profiles** and click **New Profile**: + +![New Profile](../assets/screenshots/new-profile.png) + +Fill in: + +| Field | Description | Example | +|-------|-------------|---------| +| **Profile Name** | Friendly name | "My XMR Pool" | +| **Miner Type** | Select miner | xmrig | +| **Pool Address** | Mining pool URL | pool.supportxmr.com:3333 | +| **Wallet Address** | Your XMR wallet | 4xxx... | +| **TLS** | Enable encryption | ✓ Recommended | + +Click **Create Profile**. + +## Step 4: Start Mining + +Two ways to start: + +1. **From Profiles**: Click the **Start** button on your profile card +2. **From Workers**: Select a profile from the dropdown and click **Start** + +![Workers Page](../assets/screenshots/workers.png) + +## Step 5: Monitor Your Miner + +### Dashboard + +The **Dashboard** shows real-time stats: + +![Dashboard](../assets/screenshots/dashboard.png) + +- **Hashrate** - Current mining speed +- **Shares** - Accepted/rejected shares +- **Uptime** - How long the miner has been running +- **Avg Diff** - Average difficulty per share +- **Pool** - Connected pool + +### Console + +View live miner output in the **Console**: + +![Console](../assets/screenshots/console.png) + +Send commands to the miner using the input field: + +| Command | Action | +|---------|--------| +| `h` | Show hashrate | +| `p` | Pause mining | +| `r` | Resume mining | +| `s` | Show results | +| `c` | Show connection info | + +## Common Pool Addresses + +| Pool | Address | +|------|---------| +| SupportXMR | `pool.supportxmr.com:3333` | +| MoneroOcean | `gulf.moneroocean.stream:10128` | +| 2Miners | `xmr.2miners.com:2222` | +| HashVault | `pool.hashvault.pro:3333` | + +## Next Steps + +- [Mining Profiles](../features/profiles.md) - Advanced profile configuration +- [Console & Logs](../features/console.md) - Using the console +- [Multi-Node Setup](../features/p2p-multinode.md) - Control remote rigs diff --git a/site-docs/index.md b/site-docs/index.md new file mode 100644 index 0000000..51bb6a7 --- /dev/null +++ b/site-docs/index.md @@ -0,0 +1,132 @@ +# Mining Dashboard + +
+Mining Dashboard +
+ +**Mining Dashboard** is a powerful, open-source multi-miner management system that lets you control XMRig, TT-Miner, and other mining software from a single, beautiful web interface. + +!!! tip "Built with Claude Code" + This entire project—backend, frontend, documentation, and tests—was developed using [Claude Code](https://claude.ai/code), Anthropic's AI-powered development assistant. See [how Claude helped build this](about/claude.md). + +## Key Features + +
+ +- :material-lightning-bolt:{ .lg .middle } **Real-time Monitoring** + + --- + + Live hashrate graphs, share statistics, and performance metrics updated every 5 seconds + +- :material-cog:{ .lg .middle } **Multi-Miner Support** + + --- + + Control XMRig (CPU) and TT-Miner (GPU) from a unified interface. Easy to extend for additional miners + +- :material-console:{ .lg .middle } **Console Access** + + --- + + Full console output with ANSI color support and stdin input for miner commands + +- :material-server-network:{ .lg .middle } **P2P Multi-Node** + + --- + + Control remote mining rigs via encrypted WebSocket connections without cloud dependencies + +- :material-database:{ .lg .middle } **Historical Data** + + --- + + SQLite-backed hashrate history with configurable retention (5m to 24h views) + +- :material-api:{ .lg .middle } **REST API** + + --- + + Full REST API with Swagger documentation for automation and integration + +
+ +## Quick Start + +```bash +# Clone the repository +git clone https://github.com/Snider/Mining.git +cd Mining + +# Build the CLI +make build + +# Start the server +./miner-cli serve +``` + +Then open [http://localhost:9090](http://localhost:9090) in your browser! + +## Screenshots + +
+ +![Dashboard](assets/screenshots/dashboard.png){ loading=lazy } + +![Profiles](assets/screenshots/profiles.png){ loading=lazy } + +![Console](assets/screenshots/console.png){ loading=lazy } + +![Nodes](assets/screenshots/nodes.png){ loading=lazy } + +
+ +## Architecture + +The Mining Dashboard consists of: + +- **Go Backend** - REST API server with miner process management +- **Angular Frontend** - Modern, responsive web interface +- **SQLite Database** - Persistent hashrate history storage +- **P2P Network** - Encrypted node-to-node communication + +```mermaid +graph TB + subgraph "Web Browser" + UI[Angular Dashboard] + end + + subgraph "Mining Server" + API[REST API :9090] + MGR[Miner Manager] + DB[(SQLite DB)] + P2P[P2P Transport :9091] + end + + subgraph "Mining Processes" + XMR[XMRig] + TTM[TT-Miner] + end + + subgraph "Remote Nodes" + RN1[Worker Node 1] + RN2[Worker Node 2] + end + + UI --> API + API --> MGR + MGR --> XMR + MGR --> TTM + MGR --> DB + P2P --> RN1 + P2P --> RN2 +``` + +## Support + +- **GitHub Issues**: [Report bugs or request features](https://github.com/Snider/Mining/issues) +- **Documentation**: You're reading it! + +## License + +This project is open source. See the repository for license details. diff --git a/site-docs/ui/overview.md b/site-docs/ui/overview.md new file mode 100644 index 0000000..46534f6 --- /dev/null +++ b/site-docs/ui/overview.md @@ -0,0 +1,128 @@ +# UI Overview + +The Mining Dashboard features a modern, responsive web interface built with Angular. + +## Layout + +``` +┌────────────────────────────────────────────────────────┐ +│ Logo Stats Bar (Hashrate, Shares, etc.) Workers │ +├────────┬───────────────────────────────────────────────┤ +│ │ │ +│ Sidebar│ Main Content Area │ +│ │ │ +│ ○ Dash │ │ +│ ○ Work │ │ +│ ○ Cons │ │ +│ ○ Pool │ │ +│ ○ Prof │ │ +│ ○ Mine │ │ +│ ○ Node │ │ +│ │ │ +├────────┴───────────────────────────────────────────────┤ +│ Status: Mining Active │ +└────────────────────────────────────────────────────────┘ +``` + +## Navigation + +### Sidebar + +| Page | Icon | Description | +|------|------|-------------| +| **Dashboard** | Chart | Main monitoring view | +| **Workers** | Server | Running miner instances | +| **Console** | Terminal | Live miner output | +| **Pools** | Globe | Connected pools | +| **Profiles** | Bookmark | Saved configurations | +| **Miners** | CPU | Install/manage miners | +| **Nodes** | Network | P2P peer management | + +### Stats Bar + +Always visible at the top: +- Hashrate +- Shares (accepted/rejected) +- Uptime +- Pool name +- Average difficulty +- Worker count + +### Worker Selector + +Dropdown to filter stats by: +- All Workers +- Individual miner + +## Pages + +### Dashboard +Real-time monitoring with hashrate charts and key metrics. + +### Workers +Start/stop miners, view running instances. + +### Console +Live terminal output with ANSI colors and command input. + +### Pools +View connected mining pools (from running miners). + +### Profiles +Create, edit, delete mining configurations. + +### Miners +Install/uninstall miner software (XMRig, TT-Miner). + +### Nodes +P2P peer management for multi-node setups. + +## Design System + +### Colors + +| Color | Usage | +|-------|-------| +| **Cyan** (#06b6d4) | Primary/accent | +| **Lime** (#a3e635) | Success, active | +| **Red** (#ef4444) | Errors, rejected | +| **Purple** (#a855f7) | Difficulty stats | +| **Slate** (#1e293b) | Backgrounds | + +### Typography + +- **Sans-serif** - UI text (system fonts) +- **Monospace** - Stats, values, code + +### Components + +- **Cards** - Profile cards, stat cards +- **Tables** - Peer list, pool list +- **Forms** - Profile creation, settings +- **Charts** - Hashrate over time +- **Badges** - Miner type, status + +## Responsive Design + +The UI adapts to different screen sizes: + +| Breakpoint | Layout | +|------------|--------| +| Desktop | Full sidebar + content | +| Tablet | Collapsible sidebar | +| Mobile | Hidden sidebar, hamburger menu | + +## Keyboard Shortcuts + +| Key | Action | +|-----|--------| +| `1-7` | Navigate to page | +| `/` | Focus search | +| `Esc` | Close modal | + +## Browser Support + +- Chrome 90+ +- Firefox 88+ +- Safari 14+ +- Edge 90+ diff --git a/site-docs/ui/screenshots.md b/site-docs/ui/screenshots.md new file mode 100644 index 0000000..e6b1b3e --- /dev/null +++ b/site-docs/ui/screenshots.md @@ -0,0 +1,134 @@ +# Screenshots + +A visual tour of the Mining Dashboard interface. + +## Dashboard + +The main monitoring view showing real-time hashrate graphs and statistics. + +![Dashboard](../assets/screenshots/dashboard.png) + +**Features shown:** + +- Stats bar with hashrate, shares, uptime, pool, avg difficulty, workers +- Hashrate chart with time range selector +- Quick stat cards (peak, efficiency, share time, difficulty) +- Worker selector dropdown + +--- + +## Profiles + +Manage your mining configurations with profile cards. + +![Profiles](../assets/screenshots/profiles.png) + +**Features shown:** + +- Profile cards with name, miner type, pool, wallet +- Start button to launch miner +- Edit and delete actions +- New Profile button + +--- + +## New Profile Form + +Create a new mining configuration. + +![New Profile](../assets/screenshots/new-profile.png) + +**Features shown:** + +- Profile name input +- Miner type selector +- Pool address field +- Wallet address field +- TLS and Huge Pages toggles + +--- + +## Workers + +View and manage running miner instances. + +![Workers](../assets/screenshots/workers.png) + +**Features shown:** + +- Profile dropdown to start new miners +- Empty state when no miners running +- Start button + +--- + +## Console + +Live terminal output with ANSI color support. + +![Console](../assets/screenshots/console.png) + +**Features shown:** + +- Worker dropdown selector +- Terminal output area +- Command input field +- Auto-scroll toggle +- Clear button + +--- + +## Miners + +Install and manage mining software. + +![Miners](../assets/screenshots/miners.png) + +**Features shown:** + +- XMRig card (installed) with version and algorithms +- TT-Miner card with Install button +- System information panel +- Uninstall option for installed miners + +--- + +## Pools + +View connected mining pool information. + +![Pools](../assets/screenshots/pools.png) + +**Features shown:** + +- Pool list from running miners +- Empty state when not mining + +--- + +## Nodes (P2P) + +Manage peer-to-peer connections for multi-node setups. + +![Nodes](../assets/screenshots/nodes.png) + +**Features shown:** + +- Local node identity card +- Node ID with copy button +- Peer/Online counters +- Connected peers table with ping, score, last seen +- Add Peer button +- Ping, View Stats, Remove actions per peer + +--- + +## Theme + +The interface uses a dark theme with: + +- **Background**: Dark slate (#0a0a12) +- **Cards**: Slightly lighter slate +- **Accent**: Cyan and lime highlights +- **Text**: White and gray variants +- **Status colors**: Green (success), Red (error), Yellow (warning)