Add MinerOps branding and project README

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

No files matched your search

+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 ## Overview
- 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
## 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 The repository contains a working early-stage application and the first
- /repairs - repair queue, notes, parts used, history, CSV export foundations of a more modular architecture. Current development is focused on
- /locations - room/rack/shelf location map turning those foundations into well-defined product domains with tested service
- /system-health - app, database, table size, route, and retention health and persistence boundaries.
## Repair workflow The longer-term product direction combines:
1. Open /repairs. - Miner inventory
2. Find the miner by MAC, IP, model, serial, or problem. - Network discovery and identity tracking
3. Add repair notes. - Repairs and maintenance
4. Select parts used and quantity. - Locations and electrical infrastructure
5. Update repair status. - Monitoring and alerts
6. Use History to edit or delete mistaken entries. - Fleet control
7. Mark Ready to Shelf or use Move to Shelf. - Scheduling and automation
8. Return the miner to an open shelf position on /locations. - 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 ## Why MinerOps?
- Diagnosing
- Waiting Parts
- In Progress
- Testing
- Ready to Shelf
- Needs Follow-up
- Completed
- Failed
- Cancelled
## 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 ### Asset and Inventory Management
- Hourly rollups: 1 year or longer
- Daily rollups: long term
- Repair, location, and MAC history: permanent
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" ### Locations and Infrastructure
pct exec 306 -- bash -lc "cd /opt/minerops && docker compose up -d --force-recreate backend || docker-compose up -d --force-recreate backend"
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 ### Automation and Scheduling
localhost-only backend port. It does not reuse the production `.env` file.
Scheduled scanning and real miner power/reboot controls are disabled.
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 ### Audit History and Reporting
./scripts/dev-env-init.sh
docker compose --env-file .env.dev -f compose.dev.yaml up -d --build 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 ## Technology Stack
docker compose --env-file .env.dev -f compose.dev.yaml ps
curl --fail --silent http://127.0.0.1:18000/api/health
```
Run the disposable clean-database baseline: Current technologies:
```bash - Python
./scripts/test-dev-baseline.sh - FastAPI
``` - Pydantic
- PostgreSQL
- Alembic
- Redis
- Docker and Docker Compose
- Nginx development gateway
The baseline uses a separate Compose project and port, verifies migrations, A typed, responsive frontend with a shared design system is planned. Its
schema, pages, retention rollups, and safety interlocks, then deletes only its technology selection has not yet been finalized in this repository.
own temporary volumes.
Stop development services without deleting their data: ## Roadmap
```bash - `v0.2 - Foundation`
docker compose --env-file .env.dev -f compose.dev.yaml down - `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 Roadmap scope and release boundaries may evolve as development continues and
different local port, change `MINEROPS_DEV_PORT` in `.env.dev`. operational requirements become clearer.
## Safety notes ## Documentation
- Do not commit .env. Detailed product, architecture, development, database, testing, and roadmap
- Do not commit backups, logs, database dumps, imports, or runtime data. documentation will live under `docs/`. That documentation set is still being
- Do not enable scanning or real miner controls in the development environment. developed, so this README does not link to files that do not yet exist.
- Check /system-health after major changes.
- Commit and push after each stable working change. ## 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.
+111
View File
@@ -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.
+40
View File
@@ -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.
+5
View File
@@ -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

+5
View File
@@ -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

+5
View File
@@ -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

+5
View File
@@ -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

+9
View File
@@ -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