Phase 2 complete.
This commit is contained in:
Aodhan Collins
308
docs/setup/DEV_SETUP.md
Normal file
308
docs/setup/DEV_SETUP.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# Development Environment Setup Guide
|
||||
|
||||
This guide covers setting up your development environment for EVE using the automated setup scripts.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Linux/macOS
|
||||
|
||||
```bash
|
||||
# Make script executable (if not already)
|
||||
chmod +x setup.sh
|
||||
|
||||
# Run setup script
|
||||
./setup.sh
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
# Run in PowerShell
|
||||
.\setup.ps1
|
||||
```
|
||||
|
||||
## What the Setup Script Does
|
||||
|
||||
The automated setup script will:
|
||||
|
||||
1. **Detect your operating system**
|
||||
- Linux (Debian/Ubuntu, Fedora/RHEL, Arch)
|
||||
- macOS
|
||||
- Windows
|
||||
|
||||
2. **Check for required dependencies**
|
||||
- Node.js (v18+)
|
||||
- Rust (latest stable)
|
||||
- npm or pnpm
|
||||
- Platform-specific system libraries
|
||||
|
||||
3. **Install missing dependencies** (with your permission)
|
||||
- Guides you through installing Node.js and Rust
|
||||
- Installs system dependencies for Tauri
|
||||
- Sets up build tools
|
||||
|
||||
4. **Configure your environment**
|
||||
- Creates `.env` file from template
|
||||
- Installs npm dependencies
|
||||
- Verifies installation
|
||||
|
||||
5. **Provide next steps**
|
||||
- Instructions for adding API keys
|
||||
- Commands to start development
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### All Platforms
|
||||
|
||||
Before running the setup script, ensure you have:
|
||||
|
||||
- **Internet connection** (for downloading dependencies)
|
||||
- **Administrator/sudo access** (for installing system packages)
|
||||
- **~500MB free disk space** (for dependencies)
|
||||
|
||||
### Platform-Specific
|
||||
|
||||
#### Linux
|
||||
- `curl` or `wget` (usually pre-installed)
|
||||
- `sudo` access for installing system packages
|
||||
|
||||
#### macOS
|
||||
- Xcode Command Line Tools (script will prompt if needed)
|
||||
- Homebrew (optional, but recommended)
|
||||
|
||||
#### Windows
|
||||
- PowerShell 5.1+ (included in Windows 10+)
|
||||
- Internet Explorer or Edge (for WebView2)
|
||||
|
||||
## Manual Installation
|
||||
|
||||
If you prefer manual setup or the automated script encounters issues, follow these steps:
|
||||
|
||||
### 1. Install Node.js
|
||||
|
||||
**Linux/macOS:**
|
||||
- Download from: https://nodejs.org/
|
||||
- Or use nvm: https://github.com/nvm-sh/nvm
|
||||
|
||||
**Windows:**
|
||||
- Download from: https://nodejs.org/
|
||||
- Run the installer and follow prompts
|
||||
|
||||
Verify installation:
|
||||
```bash
|
||||
node -v # Should show v18.0.0 or higher
|
||||
npm -v # Should show npm version
|
||||
```
|
||||
|
||||
### 2. Install Rust
|
||||
|
||||
**All platforms:**
|
||||
```bash
|
||||
# Linux/macOS
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
|
||||
# Windows (PowerShell)
|
||||
# Download and run: https://win.rustup.rs/x86_64
|
||||
```
|
||||
|
||||
Verify installation:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
### 3. Install System Dependencies
|
||||
|
||||
#### Debian/Ubuntu
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install libwebkit2gtk-4.0-dev \
|
||||
build-essential \
|
||||
curl \
|
||||
wget \
|
||||
file \
|
||||
libssl-dev \
|
||||
libgtk-3-dev \
|
||||
libayatana-appindicator3-dev \
|
||||
librsvg2-dev
|
||||
```
|
||||
|
||||
#### Fedora/RHEL
|
||||
```bash
|
||||
sudo dnf install webkit2gtk4.0-devel \
|
||||
openssl-devel \
|
||||
curl \
|
||||
wget \
|
||||
file \
|
||||
libappindicator-gtk3-devel \
|
||||
librsvg2-devel
|
||||
```
|
||||
|
||||
#### Arch Linux
|
||||
```bash
|
||||
sudo pacman -S webkit2gtk \
|
||||
base-devel \
|
||||
curl \
|
||||
wget \
|
||||
file \
|
||||
openssl \
|
||||
gtk3 \
|
||||
libappindicator-gtk3 \
|
||||
librsvg
|
||||
```
|
||||
|
||||
#### macOS
|
||||
```bash
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
#### Windows
|
||||
- Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
|
||||
- Select "Desktop development with C++"
|
||||
- Select "Windows 10/11 SDK"
|
||||
- Install [WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
|
||||
|
||||
### 4. Install Project Dependencies
|
||||
|
||||
```bash
|
||||
# Clone the repository (if you haven't already)
|
||||
cd eve-alpha
|
||||
|
||||
# Install npm dependencies
|
||||
npm install
|
||||
|
||||
# Setup environment file
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### 5. Configure API Keys
|
||||
|
||||
Edit `.env` and add your API keys:
|
||||
|
||||
```env
|
||||
VITE_OPENROUTER_API_KEY=sk-or-v1-your-key-here
|
||||
VITE_ELEVENLABS_API_KEY=your-key-here # Optional
|
||||
```
|
||||
|
||||
Get your API keys:
|
||||
- **OpenRouter**: https://openrouter.ai/keys (required)
|
||||
- **ElevenLabs**: https://elevenlabs.io (optional, for TTS)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Script Fails to Detect Dependencies
|
||||
|
||||
If the script doesn't detect installed tools:
|
||||
|
||||
1. **Restart your terminal** after installing Node.js or Rust
|
||||
2. **Source the cargo environment** (Linux/macOS):
|
||||
```bash
|
||||
source $HOME/.cargo/env
|
||||
```
|
||||
3. **Add to PATH** (Windows): Ensure Node.js and Rust are in your system PATH
|
||||
|
||||
### Permission Denied Errors (Linux/macOS)
|
||||
|
||||
```bash
|
||||
# Make script executable
|
||||
chmod +x setup.sh
|
||||
|
||||
# If system package installation fails
|
||||
sudo ./setup.sh # Not recommended, use sudo only for package installs
|
||||
```
|
||||
|
||||
### npm Install Fails
|
||||
|
||||
```bash
|
||||
# Clear cache and reinstall
|
||||
rm -rf node_modules package-lock.json
|
||||
npm cache clean --force
|
||||
npm install
|
||||
```
|
||||
|
||||
### Rust Compilation Errors (Linux)
|
||||
|
||||
Ensure all system dependencies are installed:
|
||||
```bash
|
||||
# Check webkit2gtk version
|
||||
pkg-config --modversion webkit2gtk-4.0
|
||||
|
||||
# Should be 2.8.0 or higher
|
||||
```
|
||||
|
||||
### Windows: "Script Cannot Be Loaded" Error
|
||||
|
||||
PowerShell execution policy may block the script:
|
||||
|
||||
```powershell
|
||||
# Run as Administrator
|
||||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
|
||||
# Then run setup script again
|
||||
.\setup.ps1
|
||||
```
|
||||
|
||||
### WebView2 Not Detected (Windows)
|
||||
|
||||
Download and install manually:
|
||||
https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section
|
||||
|
||||
## Verifying Your Setup
|
||||
|
||||
After running the setup script, verify everything works:
|
||||
|
||||
```bash
|
||||
# 1. Check all tools are installed
|
||||
node -v
|
||||
npm -v
|
||||
rustc --version
|
||||
cargo --version
|
||||
|
||||
# 2. Start development server
|
||||
npm run tauri:dev
|
||||
|
||||
# 3. If the app window opens and you see the chat interface, you're all set!
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
Once setup is complete:
|
||||
|
||||
```bash
|
||||
# Start development with hot-reload
|
||||
npm run tauri:dev
|
||||
|
||||
# Run frontend only (browser)
|
||||
npm run dev
|
||||
|
||||
# Build for production
|
||||
npm run tauri:build
|
||||
|
||||
# Lint code
|
||||
npm run lint
|
||||
|
||||
# Format code
|
||||
npm run format
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues not covered here:
|
||||
|
||||
1. Check the [main README](../../README.md)
|
||||
2. Review [SETUP_COMPLETE.md](./SETUP_COMPLETE.md) for detailed troubleshooting
|
||||
3. Check [GitHub Issues](https://github.com/your-repo/eve-alpha/issues)
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful setup:
|
||||
|
||||
1. ✅ Edit `.env` with your API keys
|
||||
2. ✅ Run `npm run tauri:dev` to start developing
|
||||
3. ✅ Read the [Development Guide](../CONTRIBUTING.md) (if available)
|
||||
4. ✅ Check out the [Roadmap](../planning/ROADMAP.md) for planned features
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: October 6, 2025
|
||||
**Supported Platforms**: Linux (Debian/Ubuntu, Fedora, Arch), macOS, Windows 10/11
|
||||
Reference in New Issue
Block a user