From 1cae60ab46ab4aa95fef6d028c7cdb6f826e5105 Mon Sep 17 00:00:00 2001 From: JC Date: Tue, 28 Jul 2026 16:49:48 +0000 Subject: [PATCH] Add MinerOps branding and project README --- README.md | 244 ++++++++++++++++++++++++++-------------- branding/BRANDING.md | 111 ++++++++++++++++++ branding/colors.md | 40 +++++++ branding/favicon.svg | 5 + branding/logo-dark.svg | 5 + branding/logo-light.svg | 5 + branding/logo.svg | 5 + branding/wordmark.svg | 9 ++ 8 files changed, 340 insertions(+), 84 deletions(-) create mode 100644 branding/BRANDING.md create mode 100644 branding/colors.md create mode 100644 branding/favicon.svg create mode 100644 branding/logo-dark.svg create mode 100644 branding/logo-light.svg create mode 100644 branding/logo.svg create mode 100644 branding/wordmark.svg diff --git a/README.md b/README.md index 6027fb1..1aa12c5 100644 --- a/README.md +++ b/README.md @@ -1,122 +1,198 @@ -# MinerOps +

+ MinerOps +

-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. +
+ Know every miner. Track every repair. Control every rack. +

-- 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. diff --git a/branding/BRANDING.md b/branding/BRANDING.md new file mode 100644 index 0000000..1cbed0e --- /dev/null +++ b/branding/BRANDING.md @@ -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. diff --git a/branding/colors.md b/branding/colors.md new file mode 100644 index 0000000..0483822 --- /dev/null +++ b/branding/colors.md @@ -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. diff --git a/branding/favicon.svg b/branding/favicon.svg new file mode 100644 index 0000000..f12dd5b --- /dev/null +++ b/branding/favicon.svg @@ -0,0 +1,5 @@ + + MinerOps favicon + + + diff --git a/branding/logo-dark.svg b/branding/logo-dark.svg new file mode 100644 index 0000000..6fe84d2 --- /dev/null +++ b/branding/logo-dark.svg @@ -0,0 +1,5 @@ + + MinerOps logo for dark backgrounds + + + diff --git a/branding/logo-light.svg b/branding/logo-light.svg new file mode 100644 index 0000000..92184da --- /dev/null +++ b/branding/logo-light.svg @@ -0,0 +1,5 @@ + + MinerOps logo for light backgrounds + + + diff --git a/branding/logo.svg b/branding/logo.svg new file mode 100644 index 0000000..1dcb79d --- /dev/null +++ b/branding/logo.svg @@ -0,0 +1,5 @@ + + MinerOps logo + + + diff --git a/branding/wordmark.svg b/branding/wordmark.svg new file mode 100644 index 0000000..a7b3f4b --- /dev/null +++ b/branding/wordmark.svg @@ -0,0 +1,9 @@ + + MinerOps wordmark + + + + + Miner + Ops +