Skip to content

Commit 96805fb

Browse files
kennethdsheridankennethdsheridan
committed
docs: slim down README, move installation details to docs/INSTALLATION.md
1 parent e406e0e commit 96805fb

2 files changed

Lines changed: 114 additions & 150 deletions

File tree

‎README.md‎

Lines changed: 16 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -10,186 +10,52 @@ Generates structured hardware inventory reports in TOML/JSON format. Designed fo
1010

1111
- [What Does This Do?](#what-does-this-do)
1212
- [Quick Start](#quick-start)
13-
- [Installation](#installation)
14-
- [Architecture Overview](#architecture-overview)
1513
- [Documentation](#documentation)
1614
- [Contributing](#contributing)
1715
- [License](#license)
1816

1917
## What Does This Do?
2018

21-
- **CPU Discovery** - Model, sockets, cores, threads, NUMA topology, cache hierarchy, frequency ranges
19+
- **CPU Discovery** - Model, sockets, cores, threads, NUMA topology, cache hierarchy
2220
- **Memory Detection** - Total capacity, module details, DDR type, speed, slot mapping
23-
- **Storage Enumeration** - NVMe/SSD/HDD detection, capacity, serial numbers, firmware, SMART status
24-
- **GPU Detection** - NVIDIA via nvidia-smi, memory, PCI topology, UUIDs, driver versions
25-
- **Network Interfaces** - MAC/IP, speed (1G-400G+), InfiniBand, driver info, link state
21+
- **Storage Enumeration** - NVMe/SSD/HDD detection, capacity, serial numbers, SMART status
22+
- **GPU Detection** - NVIDIA via nvidia-smi, memory, PCI topology, UUIDs
23+
- **Network Interfaces** - MAC/IP, speed (1G-400G+), InfiniBand, driver info
2624
- **System Information** - BIOS, BMC/IPMI, chassis serial, motherboard specs
2725

2826
## Quick Start
2927

30-
Get up and running in minutes:
28+
**Recommended: Nix build** (automatically handles all dependencies)
3129

3230
```bash
33-
# 1. Clone and build
31+
# Install Nix (if not already installed)
32+
curl -L https://install.determinate.systems/nix | sh -s -- install
33+
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
34+
35+
# Clone, build, and run
3436
git clone https://github.com/sfcompute/hardware_report.git
3537
cd hardware_report
36-
cargo build
37-
38-
# 2. Run hardware discovery
38+
nix build
3939
sudo ./result/bin/hardware_report
40-
41-
# Output: <chassis_serial>_hardware_report.toml
42-
```
43-
44-
**Need more details?** See our detailed guides:
45-
- **[Installation](#installation)** - Complete setup instructions for all environments
46-
- **[Architecture Overview](#architecture-overview)** - Hexagonal architecture and design
47-
48-
## Installation
49-
50-
### Option 1: Pre-built Releases (Recommended)
51-
52-
Download from [GitHub Releases](https://github.com/sfcompute/hardware_report/releases):
53-
54-
```bash
55-
# Debian/Ubuntu package
56-
curl -sL https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
57-
| grep "browser_download_url.*\.deb" | cut -d '"' -f 4 | wget -qi -
58-
sudo apt install -y ./hardware-report_*_amd64.deb
59-
sudo hardware_report
60-
```
61-
62-
### Option 2: Nix Build
63-
64-
```bash
65-
# One-liner: install Nix + build + run
66-
curl -L https://install.determinate.systems/nix | sh -s -- install && \
67-
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh && \
68-
git clone https://github.com/sfcompute/hardware_report.git && cd hardware_report && \
69-
nix build && sudo ./result/bin/hardware_report
70-
```
71-
72-
**Development shell:**
73-
```bash
74-
nix develop
75-
cargo build --release
7640
```
7741

78-
### Option 3: Cargo Install
42+
Output: `<chassis_serial>_hardware_report.toml`
7943

80-
```bash
81-
git clone https://github.com/sfcompute/hardware_report.git && cd hardware_report
82-
cargo install --path .
83-
sudo hardware_report
84-
```
85-
86-
### Option 4: Traditional Cargo Build
87-
88-
**Ubuntu/Debian:**
89-
```bash
90-
sudo apt-get update && sudo apt-get install -y \
91-
build-essential pkg-config libssl-dev git \
92-
numactl ipmitool ethtool util-linux pciutils
93-
94-
git clone https://github.com/sfcompute/hardware_report.git && cd hardware_report
95-
cargo build --release
96-
sudo ./target/release/hardware_report
97-
```
98-
99-
**RHEL/Fedora:**
100-
```bash
101-
sudo dnf groupinstall "Development Tools"
102-
sudo dnf install pkg-config openssl-devel numactl ipmitool ethtool util-linux pciutils
103-
104-
cargo build --release
105-
```
106-
107-
### Runtime Dependencies
108-
109-
| Tool | Purpose |
110-
|------|---------|
111-
| `numactl` | NUMA topology |
112-
| `ipmitool` | BMC/IPMI data |
113-
| `ethtool` | Network interface details |
114-
| `lspci` | PCI device enumeration |
115-
| `dmidecode` | System/BIOS/memory info |
116-
| `nvidia-smi` | GPU detection (optional) |
117-
118-
> **Note:** Nix builds bundle all dependencies automatically.
119-
120-
## Architecture Overview
121-
122-
Built with **hexagonal (ports & adapters) architecture** for clean separation of concerns:
123-
124-
```
125-
┌──────────────────────────────────────┐
126-
│ Core Domain (Pure) │
127-
│ │
128-
Primary Ports │ ┌────────────────────────────┐ │ Secondary Ports
129-
(Inbound) │ │ Domain Services │ │ (Outbound)
130-
│ │ • HardwareCollectionSvc │ │
131-
┌─────────────┐ │ │ • ReportGenerationSvc │ │ ┌──────────────────┐
132-
│ CLI │───►│ └────────────────────────────┘ │───►│ System Adapters │
133-
│ │ │ │ │ • LinuxProvider │
134-
│ hardware_ │ │ ┌────────────────────────────┐ │ │ • MacOSProvider │
135-
│ report │ │ │ Domain Entities │ │ └──────────────────┘
136-
└─────────────┘ │ │ • CpuInfo, MemoryInfo │ │
137-
│ │ • StorageInfo, GpuInfo │ │ ┌──────────────────┐
138-
┌─────────────┐ │ │ • NetworkInfo, SystemInfo │ │───►│ Command Executor │
139-
│ Library │───►│ └────────────────────────────┘ │ │ • UnixExecutor │
140-
│ │ │ │ └──────────────────┘
141-
│ create_ │ │ ┌────────────────────────────┐ │
142-
│ service() │ │ │ Pure Parsers │ │ ┌──────────────────┐
143-
└─────────────┘ │ │ • CPU, Memory, Storage │ │───►│ Publishers │
144-
│ │ • GPU, Network, System │ │ │ • FilePublisher │
145-
│ └────────────────────────────┘ │ │ • HttpPublisher │
146-
└──────────────────────────────────────┘ └──────────────────┘
147-
```
148-
149-
**Why Hexagonal Architecture?**
150-
- **Testable** - Mock any external dependency for thorough testing
151-
- **Flexible** - Swap system providers or publishers independently
152-
- **Maintainable** - Clear boundaries between business logic and infrastructure
153-
- **Platform Independent** - Core domain stays pure, adapters handle OS specifics
154-
155-
### Sample Output
156-
157-
```
158-
System Summary:
159-
==============
160-
CPU: AMD EPYC 7763 (2 Sockets, 64 Cores/Socket, 2 Threads/Core)
161-
Memory: 512GB DDR4 @ 3200 MHz
162-
Storage: 15.36 TB (4x 3.84TB NVMe)
163-
GPUs: 8x NVIDIA H100 80GB HBM3
164-
Network: 2x 100GbE, 4x 400Gb InfiniBand
165-
BIOS: AMI 2.4.3 (01/15/2024)
166-
Chassis: SuperMicro (S/N: S454857X9822867)
167-
```
44+
**Other installation methods:** See [docs/INSTALLATION.md](docs/INSTALLATION.md)
16845

16946
## Documentation
17047

17148
| Document | Description |
17249
|----------|-------------|
173-
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Hexagonal architecture deep dive |
50+
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | All installation methods (Nix, Cargo, pre-built releases) |
51+
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Hexagonal architecture overview |
17452
| [docs/API.md](docs/API.md) | Library API reference |
175-
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Production deployment guide |
17653

17754
## Contributing
17855

179-
Found a bug or want to add something? We welcome contributions!
180-
181-
**Quick Development Workflow:**
18256
```bash
183-
# 1. Fork and clone
184-
git clone https://github.com/your-username/hardware_report.git
185-
186-
# 2. Set up development environment
187-
nix develop # or follow traditional Rust setup
188-
189-
# 3. Make changes and test
57+
nix develop
19058
cargo test && cargo clippy && cargo fmt
191-
192-
# 4. Submit PR with descriptive commit messages
19359
```
19460

19561
## License

‎docs/INSTALLATION.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Installation Guide
2+
3+
## Table of Contents
4+
5+
- [Nix Build (Recommended)](#nix-build-recommended)
6+
- [Pre-built Releases](#pre-built-releases)
7+
- [Cargo Install](#cargo-install)
8+
- [Traditional Cargo Build](#traditional-cargo-build)
9+
- [Runtime Dependencies](#runtime-dependencies)
10+
11+
## Nix Build (Recommended)
12+
13+
Nix automatically handles all build and runtime dependencies.
14+
15+
```bash
16+
# Install Nix (if not already installed)
17+
curl -L https://install.determinate.systems/nix | sh -s -- install
18+
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
19+
20+
# Clone, build, and run
21+
git clone https://github.com/sfcompute/hardware_report.git
22+
cd hardware_report
23+
nix build
24+
sudo ./result/bin/hardware_report
25+
```
26+
27+
**Development shell:**
28+
```bash
29+
nix develop
30+
cargo build --release
31+
```
32+
33+
## Pre-built Releases
34+
35+
Download from [GitHub Releases](https://github.com/sfcompute/hardware_report/releases):
36+
37+
**Debian/Ubuntu package:**
38+
```bash
39+
curl -sL https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
40+
| grep "browser_download_url.*\.deb" | cut -d '"' -f 4 | wget -qi -
41+
sudo apt install -y ./hardware-report_*_amd64.deb
42+
sudo hardware_report
43+
```
44+
45+
**Standalone binary:**
46+
```bash
47+
curl -sL https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
48+
| grep "browser_download_url.*tar.gz" | cut -d '"' -f 4 | wget -qi -
49+
tar xzf hardware_report-linux-x86_64-*.tar.gz
50+
sudo ./hardware_report-linux-x86_64
51+
```
52+
53+
## Cargo Install
54+
55+
```bash
56+
git clone https://github.com/sfcompute/hardware_report.git
57+
cd hardware_report
58+
cargo install --path .
59+
sudo hardware_report
60+
```
61+
62+
## Traditional Cargo Build
63+
64+
**Ubuntu/Debian:**
65+
```bash
66+
sudo apt-get update && sudo apt-get install -y \
67+
build-essential pkg-config libssl-dev git \
68+
numactl ipmitool ethtool util-linux pciutils
69+
70+
git clone https://github.com/sfcompute/hardware_report.git
71+
cd hardware_report
72+
cargo build --release
73+
sudo ./target/release/hardware_report
74+
```
75+
76+
**RHEL/Fedora:**
77+
```bash
78+
sudo dnf groupinstall "Development Tools"
79+
sudo dnf install pkg-config openssl-devel numactl ipmitool ethtool util-linux pciutils
80+
81+
git clone https://github.com/sfcompute/hardware_report.git
82+
cd hardware_report
83+
cargo build --release
84+
sudo ./target/release/hardware_report
85+
```
86+
87+
## Runtime Dependencies
88+
89+
| Tool | Purpose |
90+
|------|---------|
91+
| `numactl` | NUMA topology |
92+
| `ipmitool` | BMC/IPMI data |
93+
| `ethtool` | Network interface details |
94+
| `lspci` | PCI device enumeration |
95+
| `dmidecode` | System/BIOS/memory info |
96+
| `nvidia-smi` | GPU detection (optional) |
97+
98+
> **Note:** Nix builds bundle all dependencies automatically.

0 commit comments

Comments
 (0)