From 577226cb4e451b9941e10e4b4d6db5ed479452ca Mon Sep 17 00:00:00 2001 From: JC Lussier Date: Tue, 28 Jul 2026 11:21:26 -0500 Subject: [PATCH] Update README.md --- README.md | 352 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 296 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 60a50d6..79fd114 100644 --- a/README.md +++ b/README.md @@ -1,82 +1,322 @@ -# MinerOps +

+ MinerOps Logo +

-MinerOps is a self-hosted mining fleet operations console for tracking, repairing, locating, and controlling WhatsMiner ASICs. +

MinerOps

-## Current deployment +

+ The self-hosted operating system for cryptocurrency mining operations. +

-- 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 +

+ Know every miner • Track every repair • Control every rack +

-## Main pages +

+ + + +

-- /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. \ No newline at end of file