Compare commits
3
Commits
4d360fac42
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 lussierj
|
390e73d950 | ||
|
lussierj
|
0dd26a3f24 | ||
|
lussierj
|
577226cb4e |
@@ -1,198 +1,322 @@
|
|||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="branding/wordmark.svg" alt="MinerOps" width="320">
|
<img src="branding/logo.png" alt="MinerOps Logo" width="180">
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h1 align="center">MinerOps</h1>
|
<h1 align="center">MinerOps</h1>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<strong>The self-hosted operating system for cryptocurrency mining operations.</strong>
|
<strong>The self-hosted operating system for cryptocurrency mining operations.</strong>
|
||||||
<br>
|
|
||||||
Know every miner. Track every repair. Control every rack.
|
|
||||||
</p>
|
</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
|
## Overview
|
||||||
|
|
||||||
MinerOps is a self-hosted platform intended to provide one authoritative source
|
MinerOps is an open-source operations platform built for cryptocurrency mining facilities.
|
||||||
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.
|
|
||||||
|
|
||||||
The repository contains a working early-stage application and the first
|
Rather than relying on spreadsheets, disconnected monitoring tools, and handwritten repair logs, MinerOps brings every operational workflow together into a single self-hosted application.
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
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.
|
||||||
- Network discovery and identity tracking
|
|
||||||
- Repairs and maintenance
|
|
||||||
- Locations and electrical infrastructure
|
|
||||||
- Monitoring and alerts
|
|
||||||
- Fleet control
|
|
||||||
- Scheduling and automation
|
|
||||||
- Historical records and reporting
|
|
||||||
|
|
||||||
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:
|
Running a mining operation requires far more than knowing whether a miner is online.
|
||||||
spreadsheets for assets, separate monitoring tools for performance, informal
|
|
||||||
repair notes, and location knowledge held by individual technicians.
|
|
||||||
|
|
||||||
That fragmentation becomes harder to manage when IP addresses change, control
|
MinerOps is designed to become the operational hub for an entire mining facility by combining:
|
||||||
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.
|
|
||||||
|
|
||||||
## 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 long-term goal is to replace multiple disconnected systems with a single source of truth for mining operations.
|
||||||
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.
|
|
||||||
|
|
||||||
### Miner Identity and Discovery
|
---
|
||||||
|
|
||||||
Associate changing network information with durable miner records. Existing
|
# Current Status
|
||||||
code includes discovery and network identity foundations; formal identity
|
|
||||||
history and transfer workflows remain planned work.
|
|
||||||
|
|
||||||
### Repairs and Maintenance
|
⚠️ **MinerOps is under active development.**
|
||||||
|
|
||||||
Build a complete service history around each miner, including repair status,
|
The current focus is building a scalable, maintainable architecture before expanding user-facing functionality.
|
||||||
notes, parts, and return-to-service workflows. Operational repair functionality
|
|
||||||
exists today, while extraction into a dedicated domain architecture is still
|
|
||||||
planned.
|
|
||||||
|
|
||||||
### Locations and Infrastructure
|
## Completed
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
- Docker-based development environment
|
- Docker-based development environment
|
||||||
- PostgreSQL data store
|
- PostgreSQL + Redis backend
|
||||||
- Redis service
|
- Alembic migration framework
|
||||||
- Alembic schema migrations
|
- Authentication
|
||||||
- Session-based authentication and login gating
|
- Role-based access control
|
||||||
- Admin, Manager, Technician, and Read Only role foundations
|
- Manual inventory schema
|
||||||
- Manual miner inventory database schema
|
- Inventory domain architecture
|
||||||
- Inventory Pydantic models
|
- Automated migration testing
|
||||||
- Inventory repository and service domain foundation
|
- Disposable development environment
|
||||||
- Automated repository and service tests for the Inventory domain
|
|
||||||
- Disposable development baseline tests
|
|
||||||
|
|
||||||
**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
|
- Asset identity & MAC history
|
||||||
transport, business rules, and persistence:
|
- 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
|
|
||||||
|
|
# Core Features
|
||||||
v
|
|
||||||
FastAPI routers
|
## 📦 Asset Inventory
|
||||||
|
|
|
||||||
v
|
Maintain a permanent identity for every miner independent of its network configuration.
|
||||||
Domain services
|
|
||||||
|
|
Planned capabilities include:
|
||||||
v
|
|
||||||
Repositories
|
- Asset IDs
|
||||||
|
|
- MAC history
|
||||||
v
|
- 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
|
PostgreSQL
|
||||||
```
|
```
|
||||||
|
|
||||||
FastAPI routers will own HTTP request and response concerns. Domain services
|
Business rules belong in 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.
|
|
||||||
|
|
||||||
## 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
|
- Python
|
||||||
- FastAPI
|
- FastAPI
|
||||||
- Pydantic
|
|
||||||
- PostgreSQL
|
- PostgreSQL
|
||||||
- Alembic
|
|
||||||
- Redis
|
- Redis
|
||||||
- Docker and Docker Compose
|
- Alembic
|
||||||
- Nginx development gateway
|
- Docker Compose
|
||||||
|
- Pydantic
|
||||||
|
|
||||||
A typed, responsive frontend with a shared design system is planned. Its
|
Planned
|
||||||
technology selection has not yet been finalized in this repository.
|
|
||||||
|
|
||||||
## 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
|
# Development Philosophy
|
||||||
operational requirements become clearer.
|
|
||||||
|
|
||||||
## Documentation
|
MinerOps is built around a few guiding principles.
|
||||||
|
|
||||||
Detailed product, architecture, development, database, testing, and roadmap
|
- Self-hosted first
|
||||||
documentation will live under `docs/`. That documentation set is still being
|
- Reliability over unnecessary complexity
|
||||||
developed, so this README does not link to files that do not yet exist.
|
- 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
|
# Roadmap
|
||||||
architecture, development workflow, and review expectations stabilize.
|
|
||||||
|
|
||||||
## 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
|
Detailed planning will be maintained in **docs/ROADMAP.md**.
|
||||||
included in this repository.
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 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