ARIA
76b491b913
- 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
132 lines
3.3 KiB
Markdown
132 lines
3.3 KiB
Markdown
# Installation
|
|
|
|
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
|
|
|
|
- **Linux** with NVIDIA proprietary drivers
|
|
- **Python 3.12+**
|
|
- **Node.js 18+** and **npm**
|
|
- **[uv](https://docs.astral.sh/uv/)** — Python package manager
|
|
- **Root/sudo access** (required for GPU hardware interactions)
|
|
|
|
### Installing uv
|
|
|
|
```bash
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
```
|
|
|
|
Or via your package manager:
|
|
|
|
```bash
|
|
# Arch Linux
|
|
sudo pacman -S uv
|
|
|
|
# Debian/Ubuntu
|
|
pip install uv
|
|
```
|
|
|
|
## Installation from Source
|
|
|
|
### Step 1: Clone the Repository
|
|
|
|
```bash
|
|
git clone <this-repo-url>.git
|
|
cd nvcurve
|
|
```
|
|
|
|
### Step 2: Build the Frontend
|
|
|
|
The frontend is a React + TypeScript + Vite application in the `frontend/` directory.
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run build
|
|
cd ..
|
|
```
|
|
|
|
This produces a `dist/` directory with the compiled static assets. The hatch build system bundles `frontend/dist` into the Python package.
|
|
|
|
### 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
|
|
```
|
|
|
|
This performs four checks:
|
|
1. **NvAPI function probe** — verifies all required functions resolve in your driver
|
|
2. **Curve read** — reads and displays your current V/F curve as a baseline
|
|
3. **Write-verify** — writes `+5 MHz` to a safe point, reads it back, and confirms the change
|
|
4. **Restore** — automatically restores the state from before the test write
|
|
|
|
If `setup` reports **Compatible**, you're ready to go.
|
|
|
|
## Frontend Development Mode
|
|
|
|
For active frontend development, run the Vite dev server instead of building:
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run dev
|
|
```
|
|
|
|
This starts a hot-reload development server. The backend server runs separately:
|
|
|
|
```bash
|
|
# In another terminal
|
|
nvcurve serve start
|
|
```
|
|
|
|
## Upgrading
|
|
|
|
```bash
|
|
cd nvcurve
|
|
git pull
|
|
cd frontend && npm run build && cd ..
|
|
uv tool install .
|
|
```
|
|
|
|
If running as a systemd service:
|
|
|
|
```bash
|
|
nvcurve service restart
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### `nvcurve` command not found
|
|
|
|
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 `npm run build` and reinstall with `uv tool install .`.
|
|
|
|
### NvAPI functions not found
|
|
|
|
Your NVIDIA driver may not expose the required undocumented functions. Try updating to the latest driver version. Run `nvcurve read --diag` for detailed diagnostics.
|
|
|
|
### 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.
|