# Installation

This guide covers installing NVCurve from source, including building the frontend.

## Prerequisites

Make sure your system has the following before proceeding:

- **Linux** (any distribution)
- **NVIDIA GPU** with proprietary drivers installed
- **Python 3.12+**
- **Node.js 18+** and **pnpm** (for frontend development)
- **Root/sudo access** (required for hardware interactions)

## Quick Install (Pre-built)

The recommended way to install NVCurve for end-use is via [uv](https://docs.astral.sh/uv/):

```bash
uv tool install nvcurve
```

This installs the CLI tool with the pre-built frontend bundled inside. After installation, verify everything works:

```bash
nvcurve setup
```

## 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
cd nvcurve
```

### Step 2: Set Up the Python Environment

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:

```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
cd ..
pip install -e .
```

### Step 5: Verify the Installation

Run the hardware compatibility check:

```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
pnpm run dev
```

This starts a hot-reload development server. The backend server runs separately:

```bash
# In another terminal
nvcurve serve start
```

## Upgrading

### Pre-built Install

```bash
uv tool upgrade nvcurve
```

If you're running NVCurve as a systemd service, restart it after upgrading:

```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`.

### 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.

### 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.