Update README.md
This commit is contained in:
lussierj committed
1 parent
421fa98292
commit
577226cb4e
1 file changed
+296
-56
@@ -1,82 +1,322 @@
|
|||||||
# MinerOps
|
<p align="center">
|
||||||
|
<img src="branding/logo.png" alt="MinerOps Logo" width="180">
|
||||||
|
</p>
|
||||||
|
|
||||||
MinerOps is a self-hosted mining fleet operations console for tracking, repairing, locating, and controlling WhatsMiner ASICs.
|
<h1 align="center">MinerOps</h1>
|
||||||
|
|
||||||
## Current deployment
|
<p align="center">
|
||||||
|
<strong>The self-hosted operating system for cryptocurrency mining operations.</strong>
|
||||||
|
</p>
|
||||||
|
|
||||||
- Hub CT: 306
|
<p align="center">
|
||||||
- Public URL: https://plexus.lussier.cc
|
Know every miner • Track every repair • Control every rack
|
||||||
- Repository: https://gitea.lussier.cc/lussierj/minerops
|
</p>
|
||||||
- Backend container: minerops-backend
|
|
||||||
- Database container: minerops-postgres
|
|
||||||
- Redis container: minerops-redis
|
|
||||||
|
|
||||||
## Main pages
|
<p align="center">
|
||||||
|
<img src="https://img.shields.io/badge/status-active%20development-orange" />
|
||||||
|
<img src="https://img.shields.io/badge/python-3.13-blue" />
|
||||||
|
<img src="https://img.shields.io/badge/license-TBD-lightgrey" />
|
||||||
|
</p>
|
||||||
|
|
||||||
- /dashboard - fleet dashboard and repair summary
|
---
|
||||||
- /repairs - repair queue, notes, parts used, history, CSV export
|
|
||||||
- /locations - room/rack/shelf location map
|
|
||||||
- /system-health - app, database, table size, route, and retention health
|
|
||||||
|
|
||||||
## Repair workflow
|
## Overview
|
||||||
|
|
||||||
1. Open /repairs.
|
MinerOps is an open-source operations platform built for cryptocurrency mining facilities.
|
||||||
2. Find the miner by MAC, IP, model, serial, or problem.
|
|
||||||
3. Add repair notes.
|
|
||||||
4. Select parts used and quantity.
|
|
||||||
5. Update repair status.
|
|
||||||
6. Use History to edit or delete mistaken entries.
|
|
||||||
7. Mark Ready to Shelf or use Move to Shelf.
|
|
||||||
8. Return the miner to an open shelf position on /locations.
|
|
||||||
|
|
||||||
## Repair statuses
|
Rather than relying on spreadsheets, disconnected monitoring tools, and handwritten repair logs, MinerOps brings every operational workflow together into a single self-hosted application.
|
||||||
|
|
||||||
- Open
|
MinerOps is designed to manage the complete lifecycle of a mining fleet, including inventory, physical locations, repairs, monitoring, maintenance, and secure remote management.
|
||||||
- Diagnosing
|
|
||||||
- Waiting Parts
|
Originally developed for WhatsMiner fleets, the platform is being built around a modular architecture that will support additional miner platforms through protocol adapters in future releases.
|
||||||
- In Progress
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Vision
|
||||||
|
|
||||||
|
Running a mining operation requires far more than knowing whether a miner is online.
|
||||||
|
|
||||||
|
MinerOps is designed to become the operational hub for an entire mining facility by combining:
|
||||||
|
|
||||||
|
- Asset Inventory
|
||||||
|
- Physical Location Management
|
||||||
|
- Repair & Maintenance Tracking
|
||||||
|
- Live Fleet Monitoring
|
||||||
|
- Historical Reporting
|
||||||
|
- Secure Remote Management
|
||||||
|
- Operational Analytics
|
||||||
|
- Fleet Automation
|
||||||
|
|
||||||
|
into one cohesive platform.
|
||||||
|
|
||||||
|
The long-term goal is to replace multiple disconnected systems with a single source of truth for mining operations.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Current Status
|
||||||
|
|
||||||
|
⚠️ **MinerOps is under active development.**
|
||||||
|
|
||||||
|
The current focus is building a scalable, maintainable architecture before expanding user-facing functionality.
|
||||||
|
|
||||||
|
## Completed
|
||||||
|
|
||||||
|
- Docker-based development environment
|
||||||
|
- PostgreSQL + Redis backend
|
||||||
|
- Alembic migration framework
|
||||||
|
- Authentication
|
||||||
|
- Role-based access control
|
||||||
|
- Manual inventory schema
|
||||||
|
- Inventory domain architecture
|
||||||
|
- Automated migration testing
|
||||||
|
- Disposable development environment
|
||||||
|
|
||||||
|
## Currently In Progress
|
||||||
|
|
||||||
|
- Inventory API
|
||||||
|
- Inventory user interface
|
||||||
|
- Domain-driven architecture migration
|
||||||
|
|
||||||
|
## Planned
|
||||||
|
|
||||||
|
- Asset identity & MAC history
|
||||||
|
- Physical location management
|
||||||
|
- Repair & work order management
|
||||||
|
- Parts inventory
|
||||||
|
- Fleet monitoring
|
||||||
|
- Site agents
|
||||||
|
- Multi-version WhatsMiner API support
|
||||||
|
- Alerting & notifications
|
||||||
|
- Bulk operations
|
||||||
|
- Scheduled automation
|
||||||
|
- Reporting & analytics
|
||||||
|
- Production deployment tools
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Core Features
|
||||||
|
|
||||||
|
## 📦 Asset Inventory
|
||||||
|
|
||||||
|
Maintain a permanent identity for every miner independent of its network configuration.
|
||||||
|
|
||||||
|
Planned capabilities include:
|
||||||
|
|
||||||
|
- Asset IDs
|
||||||
|
- MAC history
|
||||||
|
- Control board tracking
|
||||||
|
- PSU serial tracking
|
||||||
|
- Firmware history
|
||||||
|
- Lifecycle management
|
||||||
|
- Tags
|
||||||
|
- Notes
|
||||||
|
- Asset movement history
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📍 Physical Location Tracking
|
||||||
|
|
||||||
|
Track exactly where every miner is installed.
|
||||||
|
|
||||||
|
Supports:
|
||||||
|
|
||||||
|
- Sites
|
||||||
|
- Rooms
|
||||||
|
- Rows
|
||||||
|
- Racks
|
||||||
|
- Shelves
|
||||||
|
- Positions
|
||||||
|
|
||||||
|
with complete movement history.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Repair Management
|
||||||
|
|
||||||
|
Track every repair from diagnosis through return to production.
|
||||||
|
|
||||||
|
Features include:
|
||||||
|
|
||||||
|
- Work orders
|
||||||
|
- Technician notes
|
||||||
|
- Parts used
|
||||||
|
- Repair history
|
||||||
- Testing
|
- Testing
|
||||||
- Ready to Shelf
|
- Attachments
|
||||||
- Needs Follow-up
|
- Maintenance mode
|
||||||
- Completed
|
|
||||||
- Failed
|
|
||||||
- Cancelled
|
|
||||||
|
|
||||||
## Retention
|
---
|
||||||
|
|
||||||
Retention is currently scheduled in dry-run mode.
|
## 📊 Fleet Monitoring
|
||||||
|
|
||||||
Current intended policy:
|
Monitor operational health across the fleet.
|
||||||
|
|
||||||
- Raw status snapshots: 30 days
|
Planned monitoring includes:
|
||||||
- Hourly rollups: 1 year or longer
|
|
||||||
- Daily rollups: long term
|
|
||||||
- Repair, location, and MAC history: permanent
|
|
||||||
|
|
||||||
Verify /system-health before switching retention to apply mode.
|
- Hashrate
|
||||||
|
- Temperature
|
||||||
|
- Fan status
|
||||||
|
- Hashboard health
|
||||||
|
- PSU status
|
||||||
|
- Pool connectivity
|
||||||
|
- Worker information
|
||||||
|
- Firmware
|
||||||
|
- Alerts
|
||||||
|
|
||||||
## Common commands
|
---
|
||||||
|
|
||||||
Health check:
|
## 🌐 Network Discovery
|
||||||
|
|
||||||
pct exec 306 -- bash -lc "curl -s http://127.0.0.1:8000/api/health"
|
Automatically discover miners while maintaining stable asset identities.
|
||||||
|
|
||||||
Rebuild backend:
|
Planned capabilities include:
|
||||||
|
|
||||||
pct exec 306 -- bash -lc "cd /opt/minerops && docker compose build backend || docker-compose build backend"
|
- Configurable scan ranges
|
||||||
pct exec 306 -- bash -lc "cd /opt/minerops && docker compose up -d --force-recreate backend || docker-compose up -d --force-recreate backend"
|
- Duplicate detection
|
||||||
|
- MAC history
|
||||||
|
- IP history
|
||||||
|
- Capability detection
|
||||||
|
- Discovery review workflow
|
||||||
|
|
||||||
Check logs:
|
---
|
||||||
|
|
||||||
pct exec 306 -- bash -lc "docker logs minerops-backend --since 30m"
|
## 🎛 Secure Remote Control
|
||||||
|
|
||||||
Git status:
|
Safely execute commands against supported miners.
|
||||||
|
|
||||||
pct exec 306 -- bash -lc "cd /opt/minerops && git status --short"
|
Examples include:
|
||||||
|
|
||||||
## Safety notes
|
- Reboot
|
||||||
|
- Shutdown
|
||||||
|
- Performance mode
|
||||||
|
- Pool configuration
|
||||||
|
- Firmware operations
|
||||||
|
|
||||||
- Do not commit .env.
|
All commands will be permission-aware, audited, and designed for safe execution.
|
||||||
- Do not commit backups, logs, database dumps, imports, or runtime data.
|
|
||||||
- Check /system-health after major changes.
|
---
|
||||||
- Commit and push after each stable working change.
|
|
||||||
|
## 🛰 Site Agents
|
||||||
|
|
||||||
|
Future releases will include lightweight Site Agents responsible for:
|
||||||
|
|
||||||
|
- Network discovery
|
||||||
|
- Miner polling
|
||||||
|
- Local command execution
|
||||||
|
- Secure communication with the MinerOps server
|
||||||
|
|
||||||
|
This architecture allows mining networks to remain isolated while still enabling centralized fleet management.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Architecture
|
||||||
|
|
||||||
|
MinerOps follows a layered architecture that separates business logic from persistence.
|
||||||
|
|
||||||
|
```
|
||||||
|
FastAPI Routers
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Service Layer
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Repository Layer
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
PostgreSQL
|
||||||
|
```
|
||||||
|
|
||||||
|
Business rules belong in Services.
|
||||||
|
|
||||||
|
Database access belongs in Repositories.
|
||||||
|
|
||||||
|
Schema changes are managed exclusively through Alembic migrations.
|
||||||
|
|
||||||
|
This architecture keeps MinerOps modular, testable, and easy to extend.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Technology Stack
|
||||||
|
|
||||||
|
Current
|
||||||
|
|
||||||
|
- Python
|
||||||
|
- FastAPI
|
||||||
|
- PostgreSQL
|
||||||
|
- Redis
|
||||||
|
- Alembic
|
||||||
|
- Docker Compose
|
||||||
|
- Pydantic
|
||||||
|
|
||||||
|
Planned
|
||||||
|
|
||||||
|
- React
|
||||||
|
- TypeScript
|
||||||
|
- Site Agents
|
||||||
|
- Protocol adapters
|
||||||
|
- Background task processing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Development Philosophy
|
||||||
|
|
||||||
|
MinerOps is built around a few guiding principles.
|
||||||
|
|
||||||
|
- Self-hosted first
|
||||||
|
- Reliability over unnecessary complexity
|
||||||
|
- Small, reviewable commits
|
||||||
|
- Test before commit
|
||||||
|
- Database changes managed through Alembic
|
||||||
|
- Business logic separated from persistence
|
||||||
|
- Secure by default
|
||||||
|
- Role-based authorization
|
||||||
|
- Comprehensive audit logging
|
||||||
|
- Incremental development over large rewrites
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Roadmap
|
||||||
|
|
||||||
|
| Version | Focus |
|
||||||
|
|----------|---------------------------|
|
||||||
|
| ✅ v0.2 | Foundation |
|
||||||
|
| 🚧 v0.3 | Inventory |
|
||||||
|
| ⏳ v0.4 | Asset Identity |
|
||||||
|
| ⏳ v0.5 | Operations |
|
||||||
|
| ⏳ v0.6 | Monitoring |
|
||||||
|
| ⏳ v0.7 | Automation |
|
||||||
|
| 🎯 v1.0 | Production Release |
|
||||||
|
|
||||||
|
Detailed planning will be maintained in **docs/ROADMAP.md**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Documentation
|
||||||
|
|
||||||
|
Project documentation is maintained in the `docs/` directory.
|
||||||
|
|
||||||
|
Documentation includes:
|
||||||
|
|
||||||
|
- Architecture
|
||||||
|
- Roadmap
|
||||||
|
- Architecture Decisions
|
||||||
|
- Development Guide
|
||||||
|
- Coding Standards
|
||||||
|
- Database Design
|
||||||
|
- API Documentation
|
||||||
|
- Deployment Guide
|
||||||
|
- Testing Guide
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Contributing
|
||||||
|
|
||||||
|
MinerOps is currently under active development.
|
||||||
|
|
||||||
|
Contributions, ideas, bug reports, and feature requests are welcome as the project continues to evolve.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# License
|
||||||
|
|
||||||
|
License to be determined.
|
||||||
Reference in new issue
Block a user