Merge branch 'web-gui' into dev

Author: thiswillbeyourgithub

.gitignore

@@ -23,3 +23,7 @@ scripts/notfinished_*
 scripts/**/*perso*
 latest_release_notes_*.md
 wdoc_user_cache_dir/
+
+docker/custom_env
+docker/vectorstore
+docker/wdoc_cache

README.md

@@ -0,0 +1,45 @@
+FROM python:3.13-slim
+
+# Set working directory to allow the gui.py to be in the same directory as where we run
+WORKDIR /app
+
+# Install system dependencies required by wdoc
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create a non-root user with UID:GID 1000:1000
+# This matches most default user IDs on Linux systems, allowing proper file permissions for volumes
+RUN groupadd -g 1000 wdoc && \
+    useradd -u 1000 -g 1000 -m -s /bin/bash wdoc
+
+# Install Python packages
+# Using uv for faster installation, but pip is fine too
+RUN pip install --no-cache-dir uv && \
+    uv pip install --system wdoc gradio && \
+    rm -rf /root/.cache
+
+# Copy the GUI script
+COPY gui.py /app/gui.py
+
+# Expose Gradio's default port
+EXPOSE 7860
+
+# Switch to non-root user for running the application
+USER wdoc
+
+# Create .local directory structure for the wdoc user and set permissions
+RUN mkdir -p /home/wdoc/.local && \
+    mkdir -p /home/wdoc/.cache/wdoc
+USER root
+RUN chown -R wdoc:wdoc /home/wdoc/.local && \
+    chown -R wdoc:wdoc /home/wdoc/.cache/wdoc && \
+    chown -R wdoc:wdoc /app
+USER wdoc
+
+# Set environment variables
+ENV GRADIO_SERVER_NAME="0.0.0.0"
+ENV HOME="/home/wdoc"
+
+# Run the Gradio app
+CMD ["python", "gui.py"]

docker/Dockerfile

@@ -0,0 +1,136 @@
+# wdoc Docker Setup
+
+This directory contains a dockerized Gradio web interface for wdoc, designed for easy deployment and use.
+
+## Quick Start
+
+1. **Configure environment variables**: Copy and edit the environment file:
+   ```bash
+   cp custom_env.example custom_env
+   # Edit custom_env to add your API keys (OPENAI_API_KEY, etc.)
+   ```
+
+2. **Start the service**:
+   ```bash
+   docker-compose up -d
+   ```
+
+3. **Access the web interface**: Open your browser to `http://localhost:7618`
+
+## Architecture
+
+- **Container user**: Runs as non-root user `wdoc` (UID:GID 1000:1000) for security
+- **Port**: Exposes Gradio on port 7618 (mapped from internal port 7860)
+- **Volumes**:
+  - `./vectorstore`: Persistent storage for document embeddings
+  - `./wdoc_cache`: LLM cache to reduce API costs and improve performance
+
+## Troubleshooting
+
+### Permission Errors
+
+If you encounter permission errors on first startup, particularly related to the cache directory, this is typically because Docker created the volume directories with root ownership.
+
+**Solution**: Change ownership of the docker directory to match the container's user (UID:GID 1000:1000):
+
+```bash
+# From the docker directory
+sudo chown -R 1000:1000 ./vectorstore ./wdoc_cache
+
+# Or if the directories don't exist yet:
+mkdir -p ./vectorstore ./wdoc_cache
+sudo chown -R 1000:1000 ./vectorstore ./wdoc_cache
+```
+
+**Alternative**: If you're running with a different user ID, you can modify the `docker-compose.yml` to use your current user:
+
+```yaml
+user: "${UID}:${GID}"
+```
+
+Then run with:
+```bash
+UID=$(id -u) GID=$(id -g) docker-compose up -d
+```
+
+### Checking Logs
+
+To view the application logs:
+```bash
+docker-compose logs -f wdoc-gui
+```
+
+### Rebuilding After Changes
+
+If you've modified `gui.py` or `Dockerfile`:
+```bash
+docker-compose down
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `custom_env` file with your configuration:
+
+```bash
+# Required: API keys for your LLM provider
+OPENAI_API_KEY=sk-...
+# Or for other providers:
+# ANTHROPIC_API_KEY=...
+# GEMINI_API_KEY=...
+
+# Optional: Default models
+WDOC_DEFAULT_MODEL=openai/gpt-4o-mini
+WDOC_DEFAULT_EMBED_MODEL=openai/text-embedding-3-small
+
+# Optional: Langfuse integration (if using)
+LANGFUSE_PUBLIC_KEY=pk-...
+LANGFUSE_SECRET_KEY=sk-...
+LANGFUSE_HOST=https://cloud.langfuse.com
+```
+
+### Volume Paths
+
+You can customize volume paths using environment variables in `docker-compose.yml`:
+
+```bash
+VECTORSTORE_PATH=/your/custom/path/vectorstore docker-compose up -d
+CACHE_PATH=/your/custom/path/cache docker-compose up -d
+```
+
+## Security Notes
+
+- The container runs as a non-root user for improved security
+- Security option `no-new-privileges` prevents privilege escalation
+- No unnecessary capabilities are granted
+- Network access is controlled (uses `host.docker.internal` for local services like Langfuse)
+
+## For Developers
+
+### Building Locally
+
+```bash
+docker build -t wdoc-gui .
+docker run -p 7618:7860 \
+  -v $(pwd)/vectorstore:/app/vectorstore \
+  -v $(pwd)/wdoc_cache:/home/wdoc/.cache/wdoc \
+  --env-file custom_env \
+  wdoc-gui
+```
+
+### Modifying the GUI
+
+The Gradio interface is defined in `gui.py`. After making changes, rebuild the container to see them take effect.
+
+## Additional Resources
+
+- [wdoc GitHub Repository](https://github.com/thiswillbeyourgithub/wdoc)
+- [wdoc Documentation](https://wdoc.readthedocs.io/)
+- [Gradio Documentation](https://gradio.app)
+
+---
+
+*This Docker setup was created with assistance from [aider.chat](https://github.com/Aider-AI/aider/)*

docker/README.md

@@ -0,0 +1,23 @@
+services:
+  wdoc-gui:
+    container_name: wdoc-gui
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "7618:7860"
+    volumes:
+      # Mount vectorstore directory to persist and share vectorstore data
+      - ${VECTORSTORE_PATH:-./vectorstore}:/app/vectorstore
+      # Optionally mount cache directory to persist LLM caches
+      - ${CACHE_PATH:-./wdoc_cache}:/home/wdoc/.cache/wdoc
+    # Load environment variables from the env file
+    env_file:
+      - custom_env
+    restart: unless-stopped
+    user: 1000:1000
+    security_opt:
+      - no-new-privileges:true
+    # if using langfuse for example
+    extra_hosts:
+     - "host.docker.internal:host-gateway"

docker/docker-compose.yml

@@ -0,0 +1,33 @@
+# wdoc Docker Environment Configuration
+# Copy this file to 'env' and customize the values for your setup
+
+# Path to vectorstore inside container (usually no need to change)
+VECTORSTORE_PATH=/app/vectorstore
+
+# Default models for wdoc
+WDOC_DEFAULT_MODEL=openrouter/google/gemini-2.5-pro
+WDOC_DEFAULT_QUERY_EVAL_MODEL=openrouter/google/gemini-2.5-flash
+WDOC_DEFAULT_EMBED_MODEL=openai/text-embedding-3-small
+
+# API Keys - REQUIRED: Add your API keys here
+# At minimum, you need an OpenRouter API key for most models
+OPENROUTER_API_KEY=your_api_key_here
+
+# Optional: Other API keys if using different providers directly
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# MISTRAL_API_KEY=
+
+# Optional: Langfuse configuration for observability
+# WDOC_LANGFUSE_PUBLIC_KEY=
+# WDOC_LANGFUSE_SECRET_KEY=
+# WDOC_LANGFUSE_HOST=
+
+# Optional: Gradio server configuration
+GRADIO_SERVER_NAME=0.0.0.0
+GRADIO_SERVER_PORT=7860
+
+# Optional: wdoc behavior settings
+# WDOC_VERBOSE=false
+# WDOC_DEBUG=false
+# WDOC_EXPIRE_CACHE_DAYS=0