merge: incorporate current main
This commit is contained in:
lussierj committed
commit
0dd26a3f24
1 file changed
+269
-145
@@ -1,198 +1,322 @@
|
||||
<p align="center">
|
||||
<img src="branding/wordmark.svg" alt="MinerOps" width="320">
|
||||
<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>
|
||||
<br>
|
||||
Know every miner. Track every repair. Control every rack.
|
||||
</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 a self-hosted platform intended to provide one authoritative source
|
||||
of truth for cryptocurrency mining operations. It is being built to connect
|
||||
asset records, network identity, repair history, physical location, telemetry,
|
||||
and operational controls without depending on a hosted management service.
|
||||
MinerOps is an open-source operations platform built for cryptocurrency mining facilities.
|
||||
|
||||
The repository contains a working early-stage application and the first
|
||||
foundations of a more modular architecture. Current development is focused on
|
||||
turning those foundations into well-defined product domains with tested service
|
||||
and persistence boundaries.
|
||||
Rather than relying on spreadsheets, disconnected monitoring tools, and handwritten repair logs, MinerOps brings every operational workflow together into a single self-hosted application.
|
||||
|
||||
The longer-term product direction combines:
|
||||
MinerOps is designed to manage the complete lifecycle of a mining fleet, including inventory, physical locations, repairs, monitoring, maintenance, and secure remote management.
|
||||
|
||||
- Miner inventory
|
||||
- Network discovery and identity tracking
|
||||
- Repairs and maintenance
|
||||
- Locations and electrical infrastructure
|
||||
- Monitoring and alerts
|
||||
- Fleet control
|
||||
- Scheduling and automation
|
||||
- Historical records and reporting
|
||||
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.
|
||||
|
||||
These areas describe the product direction, not a claim that every workflow is
|
||||
complete or ready for production use.
|
||||
---
|
||||
|
||||
## Why MinerOps?
|
||||
# Vision
|
||||
|
||||
Mining operations often accumulate several partial versions of the truth:
|
||||
spreadsheets for assets, separate monitoring tools for performance, informal
|
||||
repair notes, and location knowledge held by individual technicians.
|
||||
Running a mining operation requires far more than knowing whether a miner is online.
|
||||
|
||||
That fragmentation becomes harder to manage when IP addresses change, control
|
||||
boards or network interfaces are replaced, equipment moves between racks, and
|
||||
repair history is incomplete. MinerOps is intended to give operators one
|
||||
self-hosted operational record that follows each miner through its full
|
||||
lifecycle.
|
||||
MinerOps is designed to become the operational hub for an entire mining facility by combining:
|
||||
|
||||
## Core Capabilities
|
||||
- Asset Inventory
|
||||
- Physical Location Management
|
||||
- Repair & Maintenance Tracking
|
||||
- Live Fleet Monitoring
|
||||
- Historical Reporting
|
||||
- Secure Remote Management
|
||||
- Operational Analytics
|
||||
- Fleet Automation
|
||||
|
||||
### Asset and Inventory Management
|
||||
into one cohesive platform.
|
||||
|
||||
Maintain stable asset records independently of a miner's current IP address.
|
||||
The inventory schema and backend domain foundation currently support Asset IDs,
|
||||
hardware identifiers, lifecycle state, tags, notes, location references, and
|
||||
seen timestamps. Inventory HTTP APIs and product workflows are the next
|
||||
application milestone.
|
||||
The long-term goal is to replace multiple disconnected systems with a single source of truth for mining operations.
|
||||
|
||||
### Miner Identity and Discovery
|
||||
---
|
||||
|
||||
Associate changing network information with durable miner records. Existing
|
||||
code includes discovery and network identity foundations; formal identity
|
||||
history and transfer workflows remain planned work.
|
||||
# Current Status
|
||||
|
||||
### Repairs and Maintenance
|
||||
⚠️ **MinerOps is under active development.**
|
||||
|
||||
Build a complete service history around each miner, including repair status,
|
||||
notes, parts, and return-to-service workflows. Operational repair functionality
|
||||
exists today, while extraction into a dedicated domain architecture is still
|
||||
planned.
|
||||
The current focus is building a scalable, maintainable architecture before expanding user-facing functionality.
|
||||
|
||||
### Locations and Infrastructure
|
||||
|
||||
Track where equipment is installed and relate miners to sites, rooms, racks,
|
||||
shelves, and operational infrastructure. Existing location workflows will be
|
||||
refined as the modular architecture develops.
|
||||
|
||||
### Monitoring and Health
|
||||
|
||||
Collect miner status and telemetry, identify stale or unhealthy equipment, and
|
||||
support operational health views. The repository contains current telemetry and
|
||||
retention foundations; broader alerting remains planned.
|
||||
|
||||
### Fleet Operations
|
||||
|
||||
Provide controlled fleet actions while keeping command policy, authorization,
|
||||
and site-local execution explicit. Existing command workflows are under active
|
||||
development and should not be treated as a finished control platform.
|
||||
|
||||
### Automation and Scheduling
|
||||
|
||||
Coordinate recurring scans, scheduled actions, retention, and other repeatable
|
||||
operations. Scheduling and automation will expand after the core inventory and
|
||||
identity domains are established.
|
||||
|
||||
### Audit History and Reporting
|
||||
|
||||
Preserve important operational changes and support practical reporting across
|
||||
assets, repairs, locations, and fleet activity. Audit-log and reporting
|
||||
foundations exist; the complete reporting model remains planned.
|
||||
|
||||
## Current Status
|
||||
|
||||
MinerOps is under active development.
|
||||
|
||||
**Current development stage:** `v0.2 - Foundation`
|
||||
|
||||
Verified foundations in the repository include:
|
||||
## Completed
|
||||
|
||||
- Docker-based development environment
|
||||
- PostgreSQL data store
|
||||
- Redis service
|
||||
- Alembic schema migrations
|
||||
- Session-based authentication and login gating
|
||||
- Admin, Manager, Technician, and Read Only role foundations
|
||||
- Manual miner inventory database schema
|
||||
- Inventory Pydantic models
|
||||
- Inventory repository and service domain foundation
|
||||
- Automated repository and service tests for the Inventory domain
|
||||
- Disposable development baseline tests
|
||||
- PostgreSQL + Redis backend
|
||||
- Alembic migration framework
|
||||
- Authentication
|
||||
- Role-based access control
|
||||
- Manual inventory schema
|
||||
- Inventory domain architecture
|
||||
- Automated migration testing
|
||||
- Disposable development environment
|
||||
|
||||
**Next application milestone:** `v0.3 - Inventory`
|
||||
## Currently In Progress
|
||||
|
||||
**Next technical feature:** Inventory API
|
||||
- Inventory API
|
||||
- Inventory user interface
|
||||
- Domain-driven architecture migration
|
||||
|
||||
## Architecture
|
||||
## Planned
|
||||
|
||||
MinerOps is moving toward a modular backend with deliberate separation between
|
||||
transport, business rules, and persistence:
|
||||
- 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
|
||||
|
||||
```text
|
||||
Frontend
|
||||
|
|
||||
v
|
||||
FastAPI routers
|
||||
|
|
||||
v
|
||||
Domain services
|
||||
|
|
||||
v
|
||||
Repositories
|
||||
|
|
||||
v
|
||||
---
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
FastAPI routers will own HTTP request and response concerns. Domain services
|
||||
will own operational rules and orchestration. Repositories will own database
|
||||
access. The Inventory domain is the first backend area established with these
|
||||
boundaries; other working application areas are still being migrated
|
||||
incrementally.
|
||||
Business rules belong in Services.
|
||||
|
||||
## Technology Stack
|
||||
Database access belongs in Repositories.
|
||||
|
||||
Current technologies:
|
||||
Schema changes are managed exclusively through Alembic migrations.
|
||||
|
||||
This architecture keeps MinerOps modular, testable, and easy to extend.
|
||||
|
||||
---
|
||||
|
||||
# Technology Stack
|
||||
|
||||
Current
|
||||
|
||||
- Python
|
||||
- FastAPI
|
||||
- Pydantic
|
||||
- PostgreSQL
|
||||
- Alembic
|
||||
- Redis
|
||||
- Docker and Docker Compose
|
||||
- Nginx development gateway
|
||||
- Alembic
|
||||
- Docker Compose
|
||||
- Pydantic
|
||||
|
||||
A typed, responsive frontend with a shared design system is planned. Its
|
||||
technology selection has not yet been finalized in this repository.
|
||||
Planned
|
||||
|
||||
## Roadmap
|
||||
- React
|
||||
- TypeScript
|
||||
- Site Agents
|
||||
- Protocol adapters
|
||||
- Background task processing
|
||||
|
||||
- `v0.2 - Foundation`
|
||||
- `v0.3 - Inventory`
|
||||
- `v0.4 - Identity`
|
||||
- `v0.5 - Operations`
|
||||
- `v0.6 - Monitoring`
|
||||
- `v0.7 - Automation`
|
||||
- `v1.0 - Production Ready`
|
||||
---
|
||||
|
||||
Roadmap scope and release boundaries may evolve as development continues and
|
||||
operational requirements become clearer.
|
||||
# Development Philosophy
|
||||
|
||||
## Documentation
|
||||
MinerOps is built around a few guiding principles.
|
||||
|
||||
Detailed product, architecture, development, database, testing, and roadmap
|
||||
documentation will live under `docs/`. That documentation set is still being
|
||||
developed, so this README does not link to files that do not yet exist.
|
||||
- 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
|
||||
|
||||
## Contributing
|
||||
---
|
||||
|
||||
MinerOps is in early development. Contribution guidelines will be added as the
|
||||
architecture, development workflow, and review expectations stabilize.
|
||||
# Roadmap
|
||||
|
||||
## License
|
||||
| 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 |
|
||||
|
||||
The MinerOps license has not yet been finalized. No license file is currently
|
||||
included in this repository.
|
||||
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