pyr0ball
82c26074d8
Bug fixes (filed as #125–#128): - Wizard step 7 read data.titles instead of data.search.titles — user-entered job titles and locations were silently dropped on every wizard run (#125) - GET /api/settings/search returned "titles" key but store expected "job_titles" — Settings → Search Prefs always showed empty even when data existed (#126) - remote_only preference not persisted during wizard setup (#127) - apply-to-profile didn't set default_resume_id in user.yaml, so future Resume Profile saves never synced back to the library entry (#128) Also: - Wizard step headings corrected (off-by-one after Training step was inserted) - Ollama host in wizard inference step now reads from saved wizard state - Resume upload during wizard now creates a library entry and sets it as default Docs: - New: docs/user-guide/daily-workflow.md — end-to-end daily usage guide - Updated: docs/user-guide/settings.md — rewritten for Vue SPA (was Streamlit) - mkdocs.yml nav: Daily Workflow added as first User Guide entry GUI help links: - web/src/composables/useDocsUrl.ts — shared docs base URL composable - Home: "Daily Workflow guide ↗" link in subtitle - Job Review: "? Docs" link in title row - Resume Library: "? Help" link in header - Settings → Resume Profile: "? Help" link in page header - Settings → Search Prefs: "? Help" link in page header
158 lines
5.5 KiB
Markdown
158 lines
5.5 KiB
Markdown
# Installation
|
|
|
|
This page walks through a full Peregrine installation from scratch.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- **Git** — to clone the repository
|
|
- **Internet connection** — `install.sh` downloads Docker/Podman and other dependencies
|
|
- **Operating system**: Ubuntu/Debian, Fedora/RHEL, Arch Linux, or macOS (with Docker Desktop)
|
|
|
|
!!! warning "Windows"
|
|
Windows is not supported. Use [WSL2 with Ubuntu](https://docs.microsoft.com/windows/wsl/install) instead.
|
|
|
|
---
|
|
|
|
## Step 1 — Clone the repository
|
|
|
|
```bash
|
|
git clone https://git.opensourcesolarpunk.com/Circuit-Forge/peregrine
|
|
cd peregrine
|
|
```
|
|
|
|
---
|
|
|
|
## Step 2 — Run install.sh
|
|
|
|
```bash
|
|
bash install.sh
|
|
```
|
|
|
|
`install.sh` performs the following automatically:
|
|
|
|
1. **Detects your platform** (Ubuntu/Debian, Fedora/RHEL, Arch, macOS)
|
|
2. **Installs Git** if not already present
|
|
3. **Installs Docker Engine** (or Podman if Docker is not available) via official repositories
|
|
4. **Adds your user to the `docker` group** so you do not need `sudo` for docker commands (Linux only — log out and back in after this)
|
|
5. **Detects NVIDIA GPUs** — if `nvidia-smi` is present and working, installs the NVIDIA Container Toolkit and configures Docker/Podman to use it
|
|
6. **Creates `.env` from `.env.example`** — edit `.env` to customise ports and model storage paths before starting
|
|
|
|
!!! note "macOS"
|
|
`install.sh` installs Docker Desktop via Homebrew (`brew install --cask docker`) then exits. Open Docker Desktop, start it, then re-run the script. Ollama can also run natively for Metal GPU-accelerated inference — see the macOS note in Step 4.
|
|
|
|
!!! note "GPU requirement"
|
|
For GPU support, `nvidia-smi` must return output before you run `install.sh`. Install your NVIDIA driver first.
|
|
|
|
---
|
|
|
|
## Step 2a — Podman users: GPU CDI setup
|
|
|
|
If you prefer rootless Podman over Docker, `install.sh` detects it and manages.sh/make use it automatically. For GPU profiles to work with Podman you must generate a CDI spec first:
|
|
|
|
```bash
|
|
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
|
|
```
|
|
|
|
This needs to be done once after driver installation. Without it, GPU profiles will start but containers will not have GPU access. Docker users can skip this step — Docker uses `--gpus all` instead of CDI.
|
|
|
|
---
|
|
|
|
## Step 3 — (Optional) Edit .env
|
|
|
|
The `.env` file controls ports and volume mount paths. The defaults work for most single-user installs:
|
|
|
|
```bash
|
|
# Main UI port
|
|
VUE_PORT=8506
|
|
|
|
# Model paths — use full absolute paths, not ~ (tilde does not expand inside containers)
|
|
DOCS_DIR=/home/yourname/Documents/JobSearch
|
|
OLLAMA_MODELS_DIR=/home/yourname/models/ollama
|
|
|
|
# Inference model defaults
|
|
OLLAMA_DEFAULT_MODEL=llama3.2:3b
|
|
|
|
# External API keys — only needed for the "remote" profile or BYOK unlock
|
|
ANTHROPIC_API_KEY=
|
|
```
|
|
|
|
Change `VUE_PORT` if 8506 is taken on your machine. See [Docker Profiles](docker-profiles.md) for a full port reference.
|
|
|
|
---
|
|
|
|
## Step 4 — Start Peregrine
|
|
|
|
Choose a profile based on your hardware:
|
|
|
|
```bash
|
|
./manage.sh start # cpu — local Ollama on CPU (recommended default)
|
|
./manage.sh start --profile single-gpu # one NVIDIA GPU
|
|
./manage.sh start --profile dual-gpu # two NVIDIA GPUs
|
|
./manage.sh start --profile remote # no local LLM — use cloud API keys only
|
|
```
|
|
|
|
`manage.sh start` runs `preflight.py` first, which checks for port conflicts and writes GPU/RAM recommendations to `.env`. Then it calls `docker compose` (or `podman compose`) with the right compose file overlay for your hardware.
|
|
|
|
!!! tip "macOS with native Ollama"
|
|
If you installed Ollama natively via Homebrew for Metal GPU inference, start with `--profile cpu`. The container API on port 8506 connects to your host's Ollama at `localhost:11434` automatically.
|
|
|
|
---
|
|
|
|
## Step 5 — Open the UI
|
|
|
|
Navigate to **http://localhost:8506** (or whatever `VUE_PORT` you set).
|
|
|
|
The first-run wizard launches automatically. See [First-Run Wizard](first-run-wizard.md) for a step-by-step guide.
|
|
|
|
---
|
|
|
|
## Supported Platforms
|
|
|
|
| Platform | Tested | Notes |
|
|
|----------|--------|-------|
|
|
| Ubuntu 22.04 / 24.04 | Yes | Primary target |
|
|
| Debian 12 | Yes | |
|
|
| Fedora 39/40 | Yes | |
|
|
| RHEL / Rocky / AlmaLinux | Yes | |
|
|
| Arch Linux / Manjaro | Yes | |
|
|
| macOS (Apple Silicon) | Yes | Docker Desktop required; GPU via native Ollama (Metal) |
|
|
| macOS (Intel) | Yes | Docker Desktop required; no GPU support |
|
|
| Windows | No | Use WSL2 with Ubuntu |
|
|
|
|
---
|
|
|
|
## GPU Support
|
|
|
|
Only NVIDIA GPUs are supported. AMD ROCm is not currently supported.
|
|
|
|
Requirements:
|
|
|
|
- NVIDIA driver installed and `nvidia-smi` working before running `install.sh`
|
|
- CUDA 12.x recommended (CUDA 11.x may work but is untested)
|
|
- Minimum 8 GB VRAM for `single-gpu` profile with default models
|
|
- **Podman users:** CDI spec required — see Step 2a above
|
|
|
|
For `dual-gpu`, both cards must be NVIDIA. GPU 0 handles Ollama (cover letters, general tasks) and GPU 1 handles the research workload. The exact behaviour is controlled by `DUAL_GPU_MODE` — see [Docker Profiles](docker-profiles.md#dual-gpu-modes).
|
|
|
|
If your GPU has less than 10 GB VRAM, `preflight.py` calculates a `CPU_OFFLOAD_GB` value and writes it to `.env`. The vLLM container picks this up via `--cpu-offload-gb` to overflow KV cache to system RAM.
|
|
|
|
---
|
|
|
|
## Stopping Peregrine
|
|
|
|
```bash
|
|
./manage.sh stop # stop all containers
|
|
./manage.sh restart # stop then start again (runs preflight first)
|
|
```
|
|
|
|
---
|
|
|
|
## Reinstalling / Clean State
|
|
|
|
```bash
|
|
./manage.sh clean # removes containers, images, and data volumes (destructive)
|
|
```
|
|
|
|
You will be prompted to type `yes` to confirm.
|