Add MinerOps branding and project README
This commit is contained in:
lussierj committed
1 parent
d1d02962da
commit
1cae60ab46
8 files changed
+340
-84
No files matched your search
@@ -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.
|
||||
@@ -0,0 +1,111 @@
|
||||
# MinerOps Brand Guidelines
|
||||
|
||||
## Brand Position
|
||||
|
||||
MinerOps is practical infrastructure for operators who need a clear, reliable
|
||||
view of mining assets, repairs, locations, and controls. The identity should
|
||||
feel precise, capable, and built for daily engineering work.
|
||||
|
||||
Primary tagline:
|
||||
|
||||
> The self-hosted operating system for cryptocurrency mining operations.
|
||||
|
||||
Secondary tagline:
|
||||
|
||||
> Know every miner. Track every repair. Control every rack.
|
||||
|
||||
## Branding Philosophy
|
||||
|
||||
- **Operational clarity:** Prefer direct language, strong hierarchy, and
|
||||
purposeful visual elements.
|
||||
- **Engineering confidence:** Use measured geometry, consistent spacing, and
|
||||
restrained color.
|
||||
- **Self-hosted independence:** Present MinerOps as dependable infrastructure
|
||||
owned and controlled by its operator.
|
||||
- **Human utility:** Keep the identity approachable and readable without
|
||||
becoming playful or ornamental.
|
||||
|
||||
## Logo System
|
||||
|
||||
The MinerOps mark combines a geometric hexagon with an angular letter M. The
|
||||
hexagon suggests infrastructure, modular systems, and engineered hardware. The
|
||||
M creates immediate product recognition.
|
||||
|
||||
Available placeholders:
|
||||
|
||||
- `logo.svg`: Primary mark for general use.
|
||||
- `logo-light.svg`: Navy and orange mark for light backgrounds.
|
||||
- `logo-dark.svg`: White and orange mark for dark backgrounds.
|
||||
- `favicon.svg`: Compact filled mark optimized for small sizes.
|
||||
- `wordmark.svg`: Symbol paired with the MinerOps name.
|
||||
|
||||
Use the supplied artwork without changing its proportions, stroke weights, or
|
||||
relative colors. Do not rotate, skew, outline, add effects, or place the mark
|
||||
inside another shape. Do not use gradients.
|
||||
|
||||
## Clear Space
|
||||
|
||||
Maintain clear space around the logo equal to at least one quarter of the
|
||||
mark's width. For the wordmark, use the hexagon's internal margin as the
|
||||
minimum clear space on every side.
|
||||
|
||||
Recommended minimum sizes:
|
||||
|
||||
- Standalone logo: 24 px digital, 8 mm print.
|
||||
- Wordmark: 120 px digital, 32 mm print.
|
||||
- Favicon: 16 px digital.
|
||||
|
||||
## Wordmark Usage
|
||||
|
||||
Use the wordmark when the audience needs explicit product identification, such
|
||||
as documentation covers, sign-in screens, repository graphics, and event
|
||||
materials. Use the standalone mark where MinerOps is already named nearby or
|
||||
space is limited.
|
||||
|
||||
Keep `Miner` in Miner Navy or White and `Ops` in Ops Orange. Do not alter the
|
||||
capitalization or insert a space between the words.
|
||||
|
||||
## Typography
|
||||
|
||||
Recommended interface and brand typefaces:
|
||||
|
||||
1. **Inter:** Primary choice for user interfaces, documentation, and marketing
|
||||
copy.
|
||||
2. **IBM Plex Sans:** Alternative for a more technical editorial voice.
|
||||
3. **IBM Plex Mono:** Recommended for asset IDs, IP addresses, serial numbers,
|
||||
logs, and other machine-oriented data.
|
||||
|
||||
Use system sans-serif fallbacks when these fonts are unavailable. Favor medium
|
||||
or semibold weights for headings and regular weight for body copy. Avoid
|
||||
condensed, decorative, or rounded display type.
|
||||
|
||||
## Spacing
|
||||
|
||||
Use a 4 px base spacing unit for digital products. Preferred increments are
|
||||
4, 8, 12, 16, 24, 32, 48, and 64 px. Align logo placement, typography, and
|
||||
supporting elements to a consistent grid.
|
||||
|
||||
Brand compositions should have enough open space to feel calm and technical.
|
||||
Avoid crowding the mark with borders, controls, or dense copy.
|
||||
|
||||
## Icon Usage
|
||||
|
||||
Use simple outline icons with consistent stroke weight and square optical
|
||||
bounds. Icons should describe actions or system states, not serve as
|
||||
decoration. Use filled icons sparingly for selected or critical states.
|
||||
|
||||
Prefer Miner Navy or Steel Gray for neutral icons, Ops Orange for active
|
||||
emphasis, and semantic colors defined by the product design system for status
|
||||
and alerts.
|
||||
|
||||
Do not force unrelated interface icons into the hexagonal logo enclosure. The
|
||||
hexagon-and-M combination is reserved for the MinerOps brand.
|
||||
|
||||
## Tagline Usage
|
||||
|
||||
Use the primary tagline for formal product positioning and first introductions.
|
||||
Use the secondary tagline for compact campaign copy, presentation endings, or
|
||||
operator-focused material.
|
||||
|
||||
Taglines should appear as supporting copy and should not be locked permanently
|
||||
to the logo artwork. Preserve the exact wording and punctuation shown above.
|
||||
@@ -0,0 +1,40 @@
|
||||
# MinerOps Color Palette
|
||||
|
||||
## Core Colors
|
||||
|
||||
| Color | Hex | Intended usage |
|
||||
| --- | --- | --- |
|
||||
| Miner Navy | `#0F172A` | Primary brand color, headings, navigation, dark surfaces, and the main logo structure |
|
||||
| Ops Orange | `#F97316` | Active emphasis, calls to action, selected states, and the M or Ops accent |
|
||||
| Steel Gray | `#475569` | Secondary text, neutral icons, borders, metadata, and supporting UI elements |
|
||||
| Light Gray | `#E2E8F0` | Dividers, subtle borders, disabled surfaces, and light neutral backgrounds |
|
||||
| White | `#FFFFFF` | Content surfaces, reversed text, and logo details on dark backgrounds |
|
||||
|
||||
## Usage Principles
|
||||
|
||||
- Use Miner Navy as the primary visual anchor.
|
||||
- Reserve Ops Orange for meaningful emphasis rather than large background
|
||||
fields.
|
||||
- Use Steel Gray for supporting information that should remain readable without
|
||||
competing with primary content.
|
||||
- Use Light Gray to organize interfaces with subtle separation.
|
||||
- Use White to preserve clarity and contrast on dark or dense surfaces.
|
||||
- Do not introduce gradients into core brand artwork.
|
||||
- Check text and control combinations for accessible contrast before production
|
||||
use.
|
||||
|
||||
## Common Combinations
|
||||
|
||||
| Context | Background | Foreground or accent |
|
||||
| --- | --- | --- |
|
||||
| Standard light surface | White | Miner Navy with Ops Orange emphasis |
|
||||
| Subtle light surface | Light Gray | Miner Navy or Steel Gray |
|
||||
| Primary dark surface | Miner Navy | White with Ops Orange emphasis |
|
||||
| Neutral metadata | White or Light Gray | Steel Gray |
|
||||
| Active control | Ops Orange | Miner Navy or White after contrast review |
|
||||
|
||||
## Color Proportions
|
||||
|
||||
For general brand compositions, use neutral surfaces and Miner Navy for most of
|
||||
the visual area. Ops Orange should typically occupy the smallest share and
|
||||
signal action, focus, or product identity.
|
||||
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
|
||||
<title id="title">MinerOps favicon</title>
|
||||
<path fill="#0F172A" d="M32 2 59 17.5v29L32 62 5 46.5v-29L32 2Z"/>
|
||||
<path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="7" d="M18 44V21l14 14 14-14v23"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 350 B |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
|
||||
<title id="title">MinerOps logo for dark backgrounds</title>
|
||||
<path fill="#FFFFFF" d="M32 3 57 17.5v29L32 61 7 46.5v-29L32 3Zm0 6.9L13 20.8v22.4l19 10.9 19-10.9V20.8L32 9.9Z"/>
|
||||
<path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="6" d="M19 43V22l13 13 13-13v21"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 416 B |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
|
||||
<title id="title">MinerOps logo for light backgrounds</title>
|
||||
<path fill="none" stroke="#0F172A" stroke-linejoin="miter" stroke-width="6" d="M32 6.5 54 19v26L32 57.5 10 45V19L32 6.5Z"/>
|
||||
<path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="6" d="M19 43V22l13 13 13-13v21"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 426 B |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
|
||||
<title id="title">MinerOps logo</title>
|
||||
<path fill="#0F172A" d="M32 3 57 17.5v29L32 61 7 46.5v-29L32 3Zm0 6.9L13 20.8v22.4l19 10.9 19-10.9V20.8L32 9.9Z"/>
|
||||
<path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="6" d="M19 43V22l13 13 13-13v21"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 395 B |
@@ -0,0 +1,9 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 72" role="img" aria-labelledby="title">
|
||||
<title id="title">MinerOps wordmark</title>
|
||||
<g transform="translate(4 4) scale(.95)">
|
||||
<path fill="#0F172A" d="M32 3 57 17.5v29L32 61 7 46.5v-29L32 3Zm0 6.9L13 20.8v22.4l19 10.9 19-10.9V20.8L32 9.9Z"/>
|
||||
<path fill="none" stroke="#F97316" stroke-linecap="square" stroke-linejoin="miter" stroke-width="6" d="M19 43V22l13 13 13-13v21"/>
|
||||
</g>
|
||||
<text x="76" y="49" fill="#0F172A" font-family="Inter, IBM Plex Sans, Arial, sans-serif" font-size="42" font-weight="700">Miner</text>
|
||||
<text x="188" y="49" fill="#F97316" font-family="Inter, IBM Plex Sans, Arial, sans-serif" font-size="42" font-weight="700">Ops</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 728 B |
Reference in new issue
Block a user