lussierj/minerops
1
0 Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases Wiki Activity

Add MinerOps branding and project README

Browse Source
This commit is contained in:
lussierj committed 2026-07-28 16:49:48 +00:00
1 parent d1d02962da
commit 1cae60ab46
8 files changed
+340 -84
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+160 -84
View File
@@ -1,122 +1,198 @@
# MinerOps
<p align="center">
<img src="branding/wordmark.svg" alt="MinerOps" width="320">
</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>
<br>
Know every miner. Track every repair. Control every rack.
</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
## Overview
## Main pages
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.
- /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
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.
## Repair workflow
The longer-term product direction combines:
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.
- 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
## Repair statuses
These areas describe the product direction, not a claim that every workflow is
complete or ready for production use.
- Open
- Diagnosing
- Waiting Parts
- In Progress
- Testing
- Ready to Shelf
- Needs Follow-up
- Completed
- Failed
- Cancelled
## Why MinerOps?
## Retention
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.
Retention is currently scheduled in dry-run mode.
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.
Current intended policy:
## Core Capabilities
- Raw status snapshots: 30 days
- Hourly rollups: 1 year or longer
- Daily rollups: long term
- Repair, location, and MAC history: permanent
### Asset and Inventory Management
Verify /system-health before switching retention to apply mode.
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.
## Common commands
### Miner Identity and Discovery
Health check:
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.
pct exec 306 -- bash -lc "curl -s http://127.0.0.1:8000/api/health"
### Repairs and Maintenance
Rebuild backend:
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.
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"
### Locations and Infrastructure
Check logs:
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.
pct exec 306 -- bash -lc "docker logs minerops-backend --since 30m"
### Monitoring and Health
Git status:
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.
pct exec 306 -- bash -lc "cd /opt/minerops && git status --short"
### Fleet Operations
## Safe local development
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.
Development uses a separate Compose project, database volume, Redis volume, and
localhost-only backend port. It does not reuse the production `.env` file.
Scheduled scanning and real miner power/reboot controls are disabled.
### Automation and Scheduling
First-time setup:
Coordinate recurring scans, scheduled actions, retention, and other repeatable
operations. Scheduling and automation will expand after the core inventory and
identity domains are established.
```bash
./scripts/dev-env-init.sh
docker compose --env-file .env.dev -f compose.dev.yaml up -d --build
### 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:
```text
Frontend
|
v
FastAPI routers
|
v
Domain services
|
v
Repositories
|
v
PostgreSQL
```
Verify the environment:
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.
```bash
docker compose --env-file .env.dev -f compose.dev.yaml ps
curl --fail --silent http://127.0.0.1:18000/api/health
```
## Technology Stack
Run the disposable clean-database baseline:
Current technologies:
```bash
./scripts/test-dev-baseline.sh
```
- Python
- FastAPI
- Pydantic
- PostgreSQL
- Alembic
- Redis
- Docker and Docker Compose
- Nginx development gateway
The baseline uses a separate Compose project and port, verifies migrations,
schema, pages, retention rollups, and safety interlocks, then deletes only its
own temporary volumes.
A typed, responsive frontend with a shared design system is planned. Its
technology selection has not yet been finalized in this repository.
Stop development services without deleting their data:
## Roadmap
```bash
docker compose --env-file .env.dev -f compose.dev.yaml down
```
- `v0.2 - Foundation`
- `v0.3 - Inventory`
- `v0.4 - Identity`
- `v0.5 - Operations`
- `v0.6 - Monitoring`
- `v0.7 - Automation`
- `v1.0 - Production Ready`
The generated `.env.dev` file is mode `0600` and ignored by Git. To use a
different local port, change `MINEROPS_DEV_PORT` in `.env.dev`.
Roadmap scope and release boundaries may evolve as development continues and
operational requirements become clearer.
## Safety notes
## Documentation
- Do not commit .env.
- Do not commit backups, logs, database dumps, imports, or runtime data.
- Do not enable scanning or real miner controls in the development environment.
- Check /system-health after major changes.
- Commit and push after each stable working change.
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.