docs: add source install instructions and systemd service guide
- Replace PyPI-only install with full source build workflow (npm + uv) - Add Blackwell GPU fork notice with extended memory offset and fan control - Add systemd service section: install commands, unit file template, config reference - Update docs/Installation.md to match npm + uv tool install . workflow - Update docs/Overview.md with Blackwell-specific capabilities
This commit is contained in:
ARIA authored and 
hhofmann committed
1 parent
d2d05bbe6d
commit
76b491b913
3 files changed
+177
-76
No files matched your search
@@ -11,21 +11,137 @@ NVCurve brings MSI Afterburner-style per-point voltage-frequency curve control t
|
||||
> [!WARNING]
|
||||
> **Experimental software.** Undocumented NvAPI functions may change between driver releases. Write operations alter GPU operational parameters. Always run `nvcurve setup` before applying changes.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Blackwell GPU Fork** — This is a specialized fork with extended memory offset support (> +1000 MHz) and custom fan curve control for Blackwell GPUs (RTX 50-series). Installing the pre-built PyPI package will NOT include these features. You must build from source.
|
||||
|
||||
|
||||
|
||||
## Installation
|
||||
## Prerequisites
|
||||
|
||||
- **Linux** with NVIDIA proprietary drivers
|
||||
- **Python 3.12+**
|
||||
- **Node.js 18+** and **npm** (for building the React frontend)
|
||||
- **[uv](https://docs.astral.sh/uv/)** — Python package manager
|
||||
- **Root/sudo access** (required for GPU hardware interactions)
|
||||
|
||||
## Installation from Source
|
||||
|
||||
```bash
|
||||
uv tool install nvcurve
|
||||
git clone <this-repo-url>.git
|
||||
cd nvcurve
|
||||
|
||||
# Build the React frontend
|
||||
cd frontend
|
||||
npm install
|
||||
npm run build
|
||||
cd ..
|
||||
|
||||
# Install the Python package (includes bundled frontend)
|
||||
uv tool install .
|
||||
```
|
||||
|
||||
After installation, verify hardware compatibility:
|
||||
|
||||
```bash
|
||||
nvcurve setup
|
||||
```
|
||||
|
||||
## Getting Started
|
||||
|
||||
```bash
|
||||
nvcurve setup # Verify hardware compatibility (do not skip)
|
||||
nvcurve # Launch web UI at http://localhost:8042
|
||||
nvcurve read # Quick curve read from CLI
|
||||
```
|
||||
|
||||
## Systemd Service
|
||||
|
||||
Install the daemon for automatic profile loading on boot and optional web server auto-start:
|
||||
|
||||
### Install with web server auto-start
|
||||
|
||||
```bash
|
||||
nvcurve service install --auto-serve --host 0.0.0.0 --port 8042
|
||||
```
|
||||
|
||||
### Install daemon only (start web server on demand)
|
||||
|
||||
```bash
|
||||
nvcurve service install
|
||||
```
|
||||
|
||||
### Manage
|
||||
|
||||
```bash
|
||||
nvcurve service start|stop|restart|status
|
||||
nvcurve service uninstall
|
||||
```
|
||||
|
||||
### Reconfigure
|
||||
|
||||
```bash
|
||||
nvcurve service configure --auto-serve # Enable web server auto-start
|
||||
nvcurve service configure --no-auto-serve # Disable web server auto-start
|
||||
nvcurve service configure --host 0.0.0.0 --port 8042
|
||||
```
|
||||
|
||||
### Manual systemd Unit
|
||||
|
||||
If you prefer managing the unit file directly, here is the template installed by `nvcurve service install`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=NVCurve NVIDIA GPU V/F Curve Daemon
|
||||
After=nvidia-persistenced.service
|
||||
Wants=nvidia-persistenced.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/python3 -m nvcurve daemon
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
Environment=PYTHONDONTWRITEBYTECODE=1
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Place at `/etc/systemd/system/nvcurve.service`, then:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now nvcurve
|
||||
```
|
||||
|
||||
### Persistent Configuration
|
||||
|
||||
The daemon reads settings from `/etc/nvcurve/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"host": "127.0.0.1",
|
||||
"port": 8042,
|
||||
"auto_serve": false,
|
||||
"max_delta_khz": 3000000,
|
||||
"auto_snapshot": true,
|
||||
"max_snapshots": 20,
|
||||
"auto_load_profiles": {
|
||||
"idx:0": "my_profile"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Setting | Description |
|
||||
|---|---|
|
||||
| `host` | Web server bind address (`0.0.0.0` for network access) |
|
||||
| `port` | Web server port (default `8042`) |
|
||||
| `auto_serve` | Auto-start web server on boot |
|
||||
| `max_delta_khz` | Safety cap for frequency offsets (default 3000 MHz) |
|
||||
| `auto_snapshot` | Save snapshot before every write |
|
||||
| `max_snapshots` | Max snapshots to keep (`0` = unlimited) |
|
||||
| `auto_load_profiles` | Per-GPU profile to apply on boot (`{gpu_key: profile_name}`) |
|
||||
|
||||
The GPU key can be a UUID, `pci:XXXX`, or `idx:N` fallback. Find your GPU key with `nvcurve gpus`.
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Overview](docs/Overview.md)** — What it does, capabilities, architecture
|
||||
@@ -36,7 +152,16 @@ nvcurve # Launch web UI at http://localhost:8042
|
||||
## Upgrading
|
||||
|
||||
```bash
|
||||
uv tool upgrade nvcurve
|
||||
cd nvcurve
|
||||
git pull
|
||||
cd frontend && npm run build && cd ..
|
||||
uv tool install .
|
||||
```
|
||||
|
||||
If running as a systemd service:
|
||||
|
||||
```bash
|
||||
nvcurve service restart
|
||||
```
|
||||
|
||||
## Changelog
|
||||
|
||||
+46
-72
@@ -2,90 +2,64 @@
|
||||
|
||||
This guide covers installing NVCurve from source, including building the frontend.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Blackwell GPU Fork** — This repository contains Blackwell-specific features (extended memory offset > +1000 MHz, fan curve control). The pre-built PyPI package does NOT include these. You must build from source.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Make sure your system has the following before proceeding:
|
||||
|
||||
- **Linux** (any distribution)
|
||||
- **NVIDIA GPU** with proprietary drivers installed
|
||||
- **Linux** with NVIDIA proprietary drivers
|
||||
- **Python 3.12+**
|
||||
- **Node.js 18+** and **pnpm** (for frontend development)
|
||||
- **Root/sudo access** (required for hardware interactions)
|
||||
- **Node.js 18+** and **npm**
|
||||
- **[uv](https://docs.astral.sh/uv/)** — Python package manager
|
||||
- **Root/sudo access** (required for GPU hardware interactions)
|
||||
|
||||
## Quick Install (Pre-built)
|
||||
|
||||
The recommended way to install NVCurve for end-use is via [uv](https://docs.astral.sh/uv/):
|
||||
### Installing uv
|
||||
|
||||
```bash
|
||||
uv tool install nvcurve
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
This installs the CLI tool with the pre-built frontend bundled inside. After installation, verify everything works:
|
||||
Or via your package manager:
|
||||
|
||||
```bash
|
||||
nvcurve setup
|
||||
# Arch Linux
|
||||
sudo pacman -S uv
|
||||
|
||||
# Debian/Ubuntu
|
||||
pip install uv
|
||||
```
|
||||
|
||||
## Installation from Source
|
||||
|
||||
Building from source is necessary if you want to modify the frontend, contribute to the project, or run a development build.
|
||||
|
||||
### Step 1: Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-username/nvcurve.git
|
||||
git clone <this-repo-url>.git
|
||||
cd nvcurve
|
||||
```
|
||||
|
||||
### Step 2: Set Up the Python Environment
|
||||
### Step 2: Build the Frontend
|
||||
|
||||
Create a virtual environment and install the Python dependencies:
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
Or if you use `uv`:
|
||||
|
||||
```bash
|
||||
uv venv
|
||||
source .venv/bin/activate
|
||||
uv pip install -e .
|
||||
```
|
||||
|
||||
### Step 3: Build the Frontend
|
||||
|
||||
The frontend is a React + TypeScript + Vite application located in the `frontend/` directory.
|
||||
|
||||
Navigate to the frontend directory and install its dependencies:
|
||||
The frontend is a React + TypeScript + Vite application in the `frontend/` directory.
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm install
|
||||
```
|
||||
|
||||
Build the production bundle:
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
This produces a `dist/` directory containing the compiled static assets. The hatch build system automatically includes `frontend/dist` in the Python package under `nvcurve/frontend/dist`.
|
||||
|
||||
### Step 4: Reinstall the Python Package
|
||||
|
||||
After building the frontend, reinstall the Python package so it picks up the new frontend assets:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
cd ..
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Step 5: Verify the Installation
|
||||
This produces a `dist/` directory with the compiled static assets. The hatch build system bundles `frontend/dist` into the Python package.
|
||||
|
||||
Run the hardware compatibility check:
|
||||
### Step 3: Install the Python Package
|
||||
|
||||
```bash
|
||||
uv tool install .
|
||||
```
|
||||
|
||||
This installs `nvcurve` as a system-wide tool with the bundled frontend.
|
||||
|
||||
### Step 4: Verify
|
||||
|
||||
```bash
|
||||
nvcurve setup
|
||||
@@ -105,7 +79,7 @@ For active frontend development, run the Vite dev server instead of building:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm run dev
|
||||
npm run dev
|
||||
```
|
||||
|
||||
This starts a hot-reload development server. The backend server runs separately:
|
||||
@@ -117,36 +91,32 @@ nvcurve serve start
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Pre-built Install
|
||||
|
||||
```bash
|
||||
uv tool upgrade nvcurve
|
||||
cd nvcurve
|
||||
git pull
|
||||
cd frontend && npm run build && cd ..
|
||||
uv tool install .
|
||||
```
|
||||
|
||||
If you're running NVCurve as a systemd service, restart it after upgrading:
|
||||
If running as a systemd service:
|
||||
|
||||
```bash
|
||||
nvcurve service restart
|
||||
```
|
||||
|
||||
### Source Install
|
||||
|
||||
```bash
|
||||
git pull
|
||||
pip install -e .
|
||||
cd frontend && pnpm install && pnpm run build
|
||||
cd .. && pip install -e .
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `nvcurve` command not found
|
||||
|
||||
Ensure your virtual environment is activated, or that the package installation directory is on your `PATH`.
|
||||
Ensure `uv` tools directory is on your `PATH`. After installing `uv`, log out and back in, or run:
|
||||
|
||||
```bash
|
||||
source ~/.local/bin/env # or wherever uv installed
|
||||
```
|
||||
|
||||
### Frontend not loading in the web UI
|
||||
|
||||
Verify that `frontend/dist` exists and contains built assets. If the directory is empty or missing, rebuild with `pnpm run build` and reinstall the Python package.
|
||||
Verify that `frontend/dist` exists and contains built assets. If the directory is empty or missing, rebuild with `npm run build` and reinstall with `uv tool install .`.
|
||||
|
||||
### NvAPI functions not found
|
||||
|
||||
@@ -155,3 +125,7 @@ Your NVIDIA driver may not expose the required undocumented functions. Try updat
|
||||
### Permission denied on hardware operations
|
||||
|
||||
All hardware-interacting commands require root. The CLI will automatically escalate via `sudo` when needed. If `sudo` is not configured for your user, run commands with `sudo` explicitly.
|
||||
|
||||
### Blackwell memory offset limited to +1000 MHz
|
||||
|
||||
The standard NVCurve on PyPI caps memory offset at +1000 MHz. This fork raises the cap to +3000 MHz for Blackwell GPUs. If you installed from PyPI, uninstall and rebuild from source.
|
||||
@@ -16,6 +16,8 @@ NVCurve provides two ways to interact with your GPU:
|
||||
## Key Capabilities
|
||||
|
||||
- **Per-Point Curve Editing** — Adjust the frequency offset for any individual voltage point on the V/F curve.
|
||||
- **Extended Memory Offset** — Memory clock offset up to +3000 MHz (Blackwell GPUs). Standard NVCurve caps at +1000 MHz.
|
||||
- **Fan Curve Control** — Custom temperature-to-fan-speed curves via NVML, adjustable through the web UI and savable in profiles.
|
||||
- **Curve Flattening** — Select multiple points and flatten them to a common frequency using anchor-point targeting.
|
||||
- **Live Monitoring** — Track GPU voltage, clock speed, temperature, and power draw in real time via NvAPI and NVML.
|
||||
- **Profile Management** — Save, load, and switch between named profiles. Set a default profile that auto-applies on startup.
|
||||
|
||||
Reference in new issue
Block a user