Pakobbix/nvcurve
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add source install instructions and systemd service guide

Browse Source 
- 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 2026-08-08 15:50:52 +02:00
1 parent d2d05bbe6d
commit 76b491b913
3 files changed
+177 -76
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/Installation.md
+46 -72
View File
@@ -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.