minerops/README.md

MinerOps

The self-hosted operating system for cryptocurrency mining operations.
Know every miner. Track every repair. Control every rack.

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.

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.

The longer-term product direction combines:

• 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

These areas describe the product direction, not a claim that every workflow is complete or ready for production use.

Why MinerOps?

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.

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.

Core Capabilities

Asset and Inventory Management

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.

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.

Repairs and Maintenance

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.

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:

• 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

Next application milestone: v0.3 - Inventory

Next technical feature: Inventory API

Architecture

MinerOps is moving toward a modular backend with deliberate separation between transport, business rules, and persistence:

Frontend
    |
    v
FastAPI routers
    |
    v
Domain services
    |
    v
Repositories
    |
    v
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.

Technology Stack

Current technologies:

• Python
• FastAPI
• Pydantic
• PostgreSQL
• Alembic
• Redis
• Docker and Docker Compose
• Nginx development gateway

A typed, responsive frontend with a shared design system is planned. Its technology selection has not yet been finalized in this repository.

Roadmap

• 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.

Documentation

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.

Contributing

MinerOps is in early development. Contribution guidelines will be added as the architecture, development workflow, and review expectations stabilize.

License

The MinerOps license has not yet been finalized. No license file is currently included in this repository.