Add Installation

Installation.md

@@ -0,0 +1,155 @@
+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.