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
|
||||
- Public URL: https://plexus.lussier.cc
|
||||
- Repository: https://gitea.lussier.cc/lussierj/minerops
|
||||
- Backend container: minerops-backend
|
||||
- Database container: minerops-postgres
|
||||
- Redis container: minerops-redis
|
||||
<p align="center">
|
||||
Know every miner • Track every repair • Control every rack
|
||||
</p>
|
||||
|
||||
## 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.
|
||||
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.
|
||||
MinerOps is an open-source operations platform built for cryptocurrency mining facilities.
|
||||
|
||||
## 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
|
||||
- Diagnosing
|
||||
- Waiting Parts
|
||||
- In Progress
|
||||
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
|
||||
- Ready to Shelf
|
||||
- Needs Follow-up
|
||||
- Completed
|
||||
- Failed
|
||||
- Cancelled
|
||||
- Attachments
|
||||
- Maintenance mode
|
||||
|
||||
## 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
|
||||
- Hourly rollups: 1 year or longer
|
||||
- Daily rollups: long term
|
||||
- Repair, location, and MAC history: permanent
|
||||
Planned monitoring includes:
|
||||
|
||||
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"
|
||||
pct exec 306 -- bash -lc "cd /opt/minerops && docker compose up -d --force-recreate backend || docker-compose up -d --force-recreate backend"
|
||||
- Configurable scan ranges
|
||||
- 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.
|
||||
- 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.
|
||||
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.
|
||||
Reference in new issue
Block a user