Skip to content

Installation

This guide covers installing DeepFix on your system. DeepFix can be installed using Docker (recommended for server deployment) or locally using Python package managers.

Prerequisites

  • Python 3.11 or higher
  • pip or uv package manager
  • (Optional) Docker and Docker Compose for containerized deployment

Docker installation is recommended for server deployment as it provides a consistent environment and easy deployment.

Step 1: Clone the Repository

git clone https://github.com/delcaux-labs/deepfix.git
cd deepfix

Step 2: Configure Environment

# Copy environment example
cp env.example .env

# Edit .env with your API keys and configuration
# See Configuration section for details

Step 3: Start with Docker Compose

# Start the server using docker-compose
docker-compose up -d

# Or using Make (if available)
make docker-compose-up

The server will be available at http://localhost:8844 by default.

See the Docker Deployment Guide for detailed instructions and configuration options.

Option 2: Local Installation

Local installation is recommended for development and testing.

Step 1: Clone the Repository

git clone https://github.com/delcaux-labs/deepfix.git
cd deepfix

Step 2: Create Virtual Environment

Using uv (recommended):

uv venv --python 3.11
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

Using venv:

python3.11 -m venv venv
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

Step 3: Install DeepFix

Using uv (recommended):

uv pip install -e .

Using pip:

pip install -e .

This installs all DeepFix packages including: - deepfix-core: Core models and types - deepfix-sdk: Python client SDK - deepfix-server: Analysis server

Step 4: Install Individual Packages (Optional)

If you only need specific components:

# Install only the SDK
cd deepfix-sdk
uv pip install -e .

# Install only the server
cd deepfix-server
uv pip install -e .

# Install only the core
cd deepfix-core
uv pip install -e .

Step 5: Verify Installation

Verify the installation by checking the version:

# Check SDK version
uv run python -c "import deepfix_sdk; print(deepfix_sdk.__version__)"

# Check server version
uv run deepfix-server version

Installation from PyPI

DeepFix packages are also available on PyPI:

# Install SDK
pip install deepfix-sdk

# Install server
pip install deepfix-server

# Install core
pip install deepfix-core

Development Installation

For development, install with all development dependencies:

# Clone repository
git clone https://github.com/delcaux-labs/deepfix.git
cd deepfix

# Create virtual environment
uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
uv pip install -e ".[dev]"

# Or install individual packages
cd deepfix-sdk
uv pip install -e ".[dev]"

Post-Installation Setup

After installation, configure DeepFix:

  1. Configure Server (if running server):
  2. Create .env file with LLM configuration

  3. See Configuration Guide for details

  4. Configure MLflow (optional):

  5. Set up MLflow tracking server
  6. Configure MLflow URI in your code

  7. See MLflow Integration Guide

  8. Verify Setup:

  9. Start the server: uv run deepfix-server launch
  10. Test client connection
  11. See Quickstart Guide for examples

Troubleshooting

Common Installation Issues

Problem: Import errors after installation

# Solution: Ensure packages are installed in editable mode
uv pip install -e .

Problem: Missing dependencies

# Solution: Reinstall with all dependencies
uv pip install --upgrade -e .

Problem: Python version mismatch

# Solution: Use Python 3.11 or higher
python --version  # Should be 3.11+
uv venv --python 3.11

Problem: Permission errors on Windows

# Solution: Run PowerShell/Command Prompt as Administrator
# Or use --user flag
uv pip install --user -e .

Server-Specific Issues

Problem: Server fails to start

  • Check if port 8844 is already in use
  • Verify .env file configuration
  • Check LLM API credentials

Problem: LLM connection errors

  • Verify DEEPFIX_LLM_API_KEY is set
  • Check DEEPFIX_LLM_BASE_URL is correct
  • Ensure network connectivity to LLM provider

See the Configuration Guide and Deployment Guide for more troubleshooting tips.

Next Steps