322 lines
6.3 KiB
Markdown
322 lines
6.3 KiB
Markdown
<p align="center">
|
|
<img src="branding/logo.png" alt="MinerOps Logo" width="180">
|
|
</p>
|
|
|
|
<h1 align="center">MinerOps</h1>
|
|
|
|
<p align="center">
|
|
<strong>The self-hosted operating system for cryptocurrency mining operations.</strong>
|
|
</p>
|
|
|
|
<p align="center">
|
|
Know every miner • Track every repair • Control every rack
|
|
</p>
|
|
|
|
<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>
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
MinerOps is an open-source operations platform built for cryptocurrency mining facilities.
|
|
|
|
Rather than relying on spreadsheets, disconnected monitoring tools, and handwritten repair logs, MinerOps brings every operational workflow together into a single self-hosted application.
|
|
|
|
MinerOps is designed to manage the complete lifecycle of a mining fleet, including inventory, physical locations, repairs, monitoring, maintenance, and secure remote management.
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
# 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
|
|
- Attachments
|
|
- Maintenance mode
|
|
|
|
---
|
|
|
|
## 📊 Fleet Monitoring
|
|
|
|
Monitor operational health across the fleet.
|
|
|
|
Planned monitoring includes:
|
|
|
|
- Hashrate
|
|
- Temperature
|
|
- Fan status
|
|
- Hashboard health
|
|
- PSU status
|
|
- Pool connectivity
|
|
- Worker information
|
|
- Firmware
|
|
- Alerts
|
|
|
|
---
|
|
|
|
## 🌐 Network Discovery
|
|
|
|
Automatically discover miners while maintaining stable asset identities.
|
|
|
|
Planned capabilities include:
|
|
|
|
- Configurable scan ranges
|
|
- Duplicate detection
|
|
- MAC history
|
|
- IP history
|
|
- Capability detection
|
|
- Discovery review workflow
|
|
|
|
---
|
|
|
|
## 🎛 Secure Remote Control
|
|
|
|
Safely execute commands against supported miners.
|
|
|
|
Examples include:
|
|
|
|
- Reboot
|
|
- Shutdown
|
|
- Performance mode
|
|
- Pool configuration
|
|
- Firmware operations
|
|
|
|
All commands will be permission-aware, audited, and designed for safe execution.
|
|
|
|
---
|
|
|
|
## 🛰 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. |