From 2fd61a054de49d47879ebc2a5758c17c93ce2c1f Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Wed, 18 Dec 2024 14:58:04 +0000 Subject: [PATCH] docs: Improve installation documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive installation guide with detailed requirements - Clarify Node.js version requirements and compatibility - Add package dependency documentation and troubleshooting - Improve error handling guidance - Update README with quick installation steps Fixes #501 Related to discussions #407 and #349 Co-Authored-By: Erkin Alp Güney --- README.md | 67 ++++------ docs/Installation/INSTALLATION.md | 203 ++++++++++++++++++++++++++++++ 2 files changed, 229 insertions(+), 41 deletions(-) create mode 100644 docs/Installation/INSTALLATION.md diff --git a/README.md b/README.md index 63c8961d..84aa255f 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ![devika screenshot](.assets/devika-screenshot.png) -> [!IMPORTANT] +> [!IMPORTANT] > This project is currently in a very early development/experimental stage. There are a lot of unimplemented/broken features at the moment. Contributions are welcome to help out with the progress! ## Table of Contents @@ -16,7 +16,7 @@ - [System Architecture](#system-architecture) - [Getting Started](#getting-started) - [Requirements](#requirements) - - [Installation](#installation) + - [Quick Installation](#quick-installation) - [How to use](#how-to-use) - [Configuration](#configuration) - [Contributing](#contributing) @@ -52,66 +52,52 @@ https://github.com/stitionai/devika/assets/26198477/cfed6945-d53b-4189-9fbe-6696 Read [**README.md**](docs/architecture) for the detailed documentation. - ## Getting Started ### Requirements ``` Version's requirements - - Python >= 3.10 and < 3.12 - - NodeJs >= 18 - - bun + - Python >= 3.10 and < 3.12 (Python 3.11 recommended) + - NodeJs >= 18 (18.x or 20.x LTS recommended) + - bun (latest version) ``` -- Install uv - Python Package manager [download](https://github.com/astral-sh/uv) -- Install bun - JavaScript runtime [download](https://bun.sh/docs/installation) -- For ollama [ollama setup guide](docs/Installation/ollama.md) (optinal: if you don't want to use the local models then you can skip this step) -- For API models, configure the API keys via setting page in UI. - - -### Installation +For detailed version compatibility information and requirements, see our [Comprehensive Installation Guide](docs/Installation/INSTALLATION.md). -To install Devika, follow these steps: +### Quick Installation -1. Clone the Devika repository: +1. Clone the repository: ```bash git clone https://github.com/stitionai/devika.git - ``` -2. Navigate to the project directory: - ```bash cd devika ``` -3. Create a virtual environment and install the required dependencies (you can use any virtual environment manager): + +2. Install dependencies and start Devika: ```bash + # Install Python dependencies uv venv - - # On macOS and Linux. - source .venv/bin/activate + source .venv/bin/activate # On Windows: .venv\Scripts\activate + uv pip install -r requirements.txt - # On Windows. - .venv\Scripts\activate + # Install browser dependencies + playwright install --with-deps - uv pip install -r requirements.txt - ``` -4. Install the playwright for browsering capabilities: - ```bash - playwright install --with-deps # installs browsers in playwright (and their deps) if required - ``` -5. Start the Devika server: - ```bash + # Start backend python devika.py - ``` -6. if everything is working fine, you see the following output: - ```bash - root: INFO : Devika is up and running! - ``` -7. Now, for frontend, open a new terminal and navigate to the `ui` directory: - ```bash + + # In a new terminal, start frontend cd ui/ bun install bun run start ``` -8. Access the Devika web interface by opening a browser and navigating to `http://127.0.0.1:3001` + +3. Access Devika at `http://127.0.0.1:3001` + +For detailed installation instructions, troubleshooting, and common issues, see: +- [Comprehensive Installation Guide](docs/Installation/INSTALLATION.md) +- [Docker Installation](docs/Installation/INSTALLATION.md#docker-installation) +- [Ollama Setup](docs/Installation/ollama.md) +- [Search Engine Setup](docs/Installation/search_engine.md) ### how to use @@ -151,7 +137,6 @@ when you first time run Devika, it will create a `config.toml` file for you in t Make sure to keep your API keys secure and do not share them publicly. For setting up the Bing and Google search API keys, follow the instructions in the [search engine setup](docs/Installation/search_engine.md) - ## Contributing We welcome contributions to enhance Devika's capabilities and improve its performance. To contribute, please see the [`CONTRIBUTING.md`](CONTRIBUTING.md) file for steps. diff --git a/docs/Installation/INSTALLATION.md b/docs/Installation/INSTALLATION.md new file mode 100644 index 00000000..1eb83645 --- /dev/null +++ b/docs/Installation/INSTALLATION.md @@ -0,0 +1,203 @@ +# Comprehensive Installation Guide + +## Table of Contents +- [Prerequisites](#prerequisites) +- [Version Requirements](#version-requirements) +- [Installation Methods](#installation-methods) + - [Local Installation](#local-installation) + - [Docker Installation](#docker-installation) +- [Package Dependencies](#package-dependencies) +- [Common Issues & Solutions](#common-issues--solutions) +- [Troubleshooting](#troubleshooting) + +## Prerequisites + +Before installing Devika, ensure you have the following tools installed: +- Git +- Python (see version requirements) +- Node.js (see version requirements) +- uv (Python package manager) +- bun (JavaScript runtime) + +## Version Requirements + +### Python Version Compatibility +- **Required**: Python >= 3.10 and < 3.12 +- **Recommended**: Python 3.11 +- **Note**: Python 3.12 support is planned but currently not available due to dependency constraints + +### Node.js Version Compatibility +- **Required**: Node.js >= 18 +- **Recommended**: Node.js 18.x LTS or 20.x LTS +- **Known Issues**: + - Node.js 19.x may have compatibility issues with some SvelteKit dependencies + - Node.js versions below 18 are not supported due to SvelteKit requirements + +### Package Manager Requirements +- **uv**: Latest version recommended +- **bun**: Latest version required for optimal frontend development + +## Installation Methods + +### Local Installation + +#### 1. Clone the Repository +```bash +git clone https://github.com/stitionai/devika.git +cd devika +``` + +#### 2. Set Up Python Environment +```bash +# Create and activate virtual environment +uv venv + +# On macOS and Linux +source .venv/bin/activate + +# On Windows +.venv\Scripts\activate + +# Install Python dependencies +uv pip install -r requirements.txt +``` + +#### 3. Install Browser Dependencies +```bash +# Install Playwright browsers and dependencies +playwright install --with-deps +``` + +#### 4. Set Up Frontend +```bash +cd ui/ +bun install +``` + +### Docker Installation + +Docker installation provides a containerized environment with all dependencies pre-configured. + +#### Prerequisites +- Docker +- Docker Compose + +#### Steps +1. Clone the repository: + ```bash + git clone https://github.com/stitionai/devika.git + cd devika + ``` + +2. Start the services: + ```bash + docker compose up -d + ``` + +3. Access Devika at `http://localhost:3000` + +#### Docker Configuration +The docker-compose.yaml file includes: +- Ollama service for local LLM support +- Backend service with API endpoints +- Frontend service with UI +- Persistent volume for database storage + +## Package Dependencies + +### Core Python Dependencies +- **flask**, **flask-cors**: Web server and CORS support +- **playwright**: Web automation and browsing capabilities +- **anthropic**, **openai**, **google-generativeai**: LLM API clients +- **ollama**: Local LLM integration +- **sqlmodel**: Database ORM +- **tiktoken**: Token counting for LLMs +- **keybert**: Keyword extraction +- **Flask-SocketIO**, **eventlet**: Real-time communication + +### Frontend Dependencies +- **SvelteKit**: Web application framework +- **Tailwind CSS**: Styling +- **Monaco Editor**: Code editor component +- **Socket.io**: Real-time communication +- **xterm**: Terminal emulation + +## Common Issues & Solutions + +### Python Environment Issues + +1. **NumPy Installation Errors** + - **Issue**: `error: Microsoft Visual C++ 14.0 or greater is required` + - **Solution**: Install Visual Studio Build Tools with C++ workload + +2. **Playwright Installation** + - **Issue**: Browser installation fails + - **Solution**: Run `playwright install --with-deps` with admin privileges + +### Node.js/Frontend Issues + +1. **SvelteKit Build Errors** + - **Issue**: `Error: Cannot find module '@sveltejs/kit'` + - **Solution**: Clear node_modules and reinstall with `bun install` + +2. **Vite Build Issues** + - **Issue**: `Error: The requested module '/node_modules/...' does not provide an export named '...'` + - **Solution**: Ensure Node.js version >= 18 is installed + +### Docker Issues + +1. **Container Start Failures** + - **Issue**: Services fail to start + - **Solution**: Check port conflicts and ensure Docker daemon is running + +2. **Volume Permission Issues** + - **Issue**: Database write permission errors + - **Solution**: Check volume permissions in docker-compose.yaml + +## Troubleshooting + +### Installation Verification +Run these commands to verify your installation: + +1. Check Python environment: +```bash +python --version +pip list +``` + +2. Verify Node.js setup: +```bash +node --version +bun --version +``` + +3. Test Devika services: +```bash +# Backend +python devika.py + +# Frontend +cd ui/ +bun run dev +``` + +### Debug Mode +To run Devika in debug mode: +```bash +# Backend with debug logging +python devika.py --debug + +# Frontend with development server +cd ui/ +bun run dev +``` + +### Logs Location +- Backend logs: `./logs/devika.log` +- Frontend build logs: `./ui/logs/` +- Docker logs: Use `docker compose logs` + +For additional help, visit: +- [GitHub Issues](https://github.com/stitionai/devika/issues) +- [Discussions](https://github.com/stitionai/devika/discussions) +- [Discord Community](https://discord.gg/CYRp43878y)