learningcircuit--local-deep-research/docs/SQLCIPHER_INSTALL.md

# SQLCipher Installation Guide

Local Deep Research uses SQLCipher to provide encrypted databases for each user. This ensures that all user data, including API keys and research results, are encrypted at rest.

## Installation by Platform

### Ubuntu/Debian Linux

SQLCipher can be easily installed from the package manager:

```bash
sudo apt update
sudo apt install sqlcipher libsqlcipher-dev
```

After installing SQLCipher, install the project with PDM:
```bash
pdm install
```

PDM will automatically select the correct Python binding for your platform:
- x86_64 Linux: `sqlcipher3-binary` (pre-compiled wheel)
- ARM64 Linux: `sqlcipher3` (builds from source)
- Other platforms: `sqlcipher3`

### macOS

Install using Homebrew:

```bash
brew install sqlcipher
```

Then install the project with PDM:
```bash
# May need to set environment variables for building
export LDFLAGS="-L$(brew --prefix sqlcipher)/lib"
export CPPFLAGS="-I$(brew --prefix sqlcipher)/include"
pdm install
```

### Windows

As of `sqlcipher3` 0.6.2+, pre-built self-contained wheels are available for Windows
(x86, x64, ARM64, Python 3.9–3.14). No compilation or system libraries needed:

```bash
pip install sqlcipher3
```

This is automatically included when you `pip install local-deep-research`.

<details>
<summary>Manual build (older versions / troubleshooting)</summary>

If you need to build from source on older Python versions:

1. Install Visual Studio 2015 or later (Community Edition works)
2. Install the "Desktop Development with C++" workload
3. Download SQLCipher source from https://github.com/sqlcipher/sqlcipher
4. Build using Visual Studio Native Tools Command Prompt

Alternatively, use WSL2 with Ubuntu.
</details>

## Alternative: Using Docker

If you have difficulty installing SQLCipher, you can run Local Deep Research in a Docker container where SQLCipher is pre-installed:

```dockerfile
FROM python:3.12-slim

# Install SQLCipher
RUN apt-get update && apt-get install -y \
    sqlcipher \
    libsqlcipher-dev \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Install Local Deep Research (SQLCipher binding selected automatically)
RUN pip install local-deep-research

CMD ["ldr", "serve"]
```

## Verifying Installation

You can verify SQLCipher is installed correctly:

```bash
# Check command line tool
sqlcipher --version

# Test Python binding
python -c "from local_deep_research.database.sqlcipher_compat import get_sqlcipher_module; get_sqlcipher_module(); print('SQLCipher is installed!')"
```

## Fallback Mode

If SQLCipher is not available, Local Deep Research will fall back to using regular SQLite databases. However, this means your data will not be encrypted at rest. A warning will be displayed when running without encryption.

## Security Notes

- Each user's database is encrypted with their password
- There is no password recovery mechanism - if a user forgets their password, their data cannot be recovered
- The encryption uses SQLCipher's default settings with AES-256
- API keys and sensitive data are only stored in the encrypted user databases

## Troubleshooting

### Linux: "Package not found"

If your distribution doesn't have SQLCipher in its repositories, you may need to build from source or use a third-party repository.

### macOS: "Library not loaded"

Make sure you've set the LDFLAGS and CPPFLAGS environment variables as shown above.

### Windows: Build errors

Ensure you're using the Visual Studio Native Tools Command Prompt and have all required dependencies installed.

### Python: "No module named sqlcipher3" or "pysqlcipher3"

**Error variants:**
- `ModuleNotFoundError: No module named 'sqlcipher3'`
- `ModuleNotFoundError: No module named 'pysqlcipher3'`

The project automatically selects the correct SQLCipher package based on your platform:
- **x86_64 Linux**: Uses `sqlcipher3-binary` (pre-compiled wheel)
- **ARM64 Linux**: Uses `sqlcipher3` (builds from source with system SQLCipher)
- **Other platforms**: Uses `sqlcipher3`

**Solution:**
1. First, ensure you have the system SQLCipher library installed:
   ```bash
   # Debian/Ubuntu
   sudo apt-get install libsqlcipher-dev

   # macOS
   brew install sqlcipher
   ```

2. Then reinstall the Python package:
   ```bash
   # If using PDM (recommended)
   pdm install

   # If NOT using PDM (e.g., pip-only setup):
   pip install --force-reinstall sqlcipher3-binary  # x86_64 Linux
   pip install --force-reinstall sqlcipher3         # Other platforms
   ```

## For Developers

To add SQLCipher to an automated installation script:

```bash
#!/bin/bash
# For Ubuntu/Debian
if command -v apt-get &> /dev/null; then
    sudo apt-get update
    sudo apt-get install -y sqlcipher libsqlcipher-dev
fi

# For macOS with Homebrew
if command -v brew &> /dev/null; then
    brew install sqlcipher
fi

# Install Python package (PDM handles platform-specific dependencies automatically)
pdm install
```