iunera/nlweb repository overview

⁠Dockersupport for Microsofts NLWeb

Forked Repo (incl. Buildpipeline): https://github.com/iunera/NLWeb/tree/docker⁠

Original Repo: https://github.com/microsoft/NLWeb⁠

Background Information about NLWeb: https://www.iunera.com/kraken/machine-learning-ai/nlweb-enables-ai-powered-websites/⁠

⁠NLWeb Docker Image

This repository contains a Dockerfile⁠ for building and running the NLWeb application, which turns your website into a knowledge base.

⁠Docker Image

The Docker image is built using a 2-stage build process to minimize the final image size:

• Stage 1: Installs all dependencies and build tools
• Stage 2: Creates the runtime environment with only the necessary components

⁠Dockerfile

Here is the content of the Dockerfile:

# Stage 1: Build stage
FROM python:3.10-slim AS builder

WORKDIR /app

# Copy requirements file
COPY code/requirements.txt .

# Install build dependencies and Python packages
RUN apt-get update && \
    apt-get install -y --no-install-recommends gcc python3-dev && \
    pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

# Stage 2: Runtime stage
FROM python:3.10-slim

# Update system packages for security
RUN apt-get update && \
    apt-get upgrade -y && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Create a non-root user and set permissions
RUN groupadd -r nlweb && \
    useradd -r -g nlweb -d /app -s /bin/bash nlweb && \
    chown -R nlweb:nlweb /app

USER nlweb

# Copy application code
COPY code/ /app/
COPY static/ /app/static/

# Remove local logs and .env file
RUN rm -r code/logs/* || true && \
    rm -r .env || true

    # Copy installed packages from builder stage
COPY --from=builder /usr/local/lib/python3.10/site-packages /usr/local/lib/python3.10/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin

# Expose the port the app runs on
EXPOSE 8000

# Set environment variables
ENV PYTHONPATH=/app
ENV PORT=8000

# Command to run the application
CMD ["python", "app-file.py"]

⁠Platform Compatibility

When built using the multi-architecture build instructions, the Docker image can run on both:

• ARM64 architecture (e.g., Apple Silicon, AWS Graviton, Raspberry Pi)
• AMD64/x86_64 architecture (e.g., Intel, AMD)

This ensures that the image can be deployed on a wide range of hardware platforms without compatibility issues.

⁠Security

The Docker image includes several security features:

• System packages are updated to the latest versions during both build and runtime stages to address security vulnerabilities
• Minimal base image (python:3.10-slim) is used to reduce attack surface
• Non-root user is used to run the application
• Only necessary packages are installed with --no-install-recommends flag to minimize image size
• Package caches are cleaned up after installation to reduce image size

⁠Building the Docker Image

⁠Single Architecture Build

To build the Docker image for your current architecture:

docker build -t iunera/nlweb:latest .

⁠Multi-Architecture Build

To build the Docker image for multiple architectures (ARM64 and AMD64), you can use Docker's buildx feature:

docker buildx build --platform linux/amd64,linux/arm64 -t iunera/nlweb:latest --push .

Note: The --push flag is required for multi-architecture builds. If you want to build without pushing to a registry, you can use the --load flag instead, but it only works for single-platform builds.

⁠Running the Docker Container

To run the Docker container:

docker run -p 8000:8000 iunera/nlweb:latest

This will start the NLWeb application and expose it on port 8000.

⁠Configuration

⁠Environment Variables

The application requires several environment variables to be set. You should pass these directly to the container without using a .env file:

docker run -p 8000:8000 \
  -e AZURE_VECTOR_SEARCH_ENDPOINT="https://your-search.search.windows.net" \
  -e AZURE_VECTOR_SEARCH_API_KEY="your-api-key" \
  -e OPENAI_API_KEY="your-openai-key" \
  iunera/nlweb:latest

For local development or testing, you can export all environment variables from your .env file using:

export $(grep -v '^#'  code/.env | xargs)

docker run -it -p 8000:8000 \
  -v ./data:/data \
  -e AZURE_VECTOR_SEARCH_ENDPOINT=${AZURE_VECTOR_SEARCH_ENDPOINT} \
  -e AZURE_VECTOR_SEARCH_API_KEY=${AZURE_VECTOR_SEARCH_API_KEY} \
  -e OPENAI_API_KEY=${OPENAI_API_KEY} \
  iunera/nlweb:latest

This command exports all non-commented variables from the code/.env file to your current shell session. However, for Docker deployments, it's recommended to pass environment variables directly to the container as shown above.

⁠Required Environment Variables

The following environment variables are required:

• AZURE_VECTOR_SEARCH_ENDPOINT: Your Azure Vector Search endpoint
• AZURE_VECTOR_SEARCH_API_KEY: Your Azure Vector Search API key
• OPENAI_API_KEY: Your OpenAI API key

See the .env.template file in the code directory for all available configuration options, but remember to pass them as environment variables rather than using a .env file.

⁠Using Docker Compose

This repository includes a docker-compose.yaml⁠ file for easy deployment of the NLWeb application.

⁠Docker Compose File

Here is the content of the docker-compose.yaml file:

services:
  nlweb:
    build:
      context: .
      dockerfile: Dockerfile
    image: iunera/nlweb:latest
    container_name: nlweb
    ports:
      - "8000:8000"
    env_file:
      - ./code/.env
    environment:
      - PYTHONPATH=/app
      - PORT=8000
    volumes:
      - ./data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    restart: unless-stopped
    user: nlweb

⁠Running with Docker Compose

To start the application using Docker Compose:

docker-compose up -d

This will build the Docker image if it doesn't exist and start the container in detached mode.

To stop the application:

docker-compose down

⁠Configuration with Docker Compose

The docker-compose.yaml file is configured to automatically use environment variables from the code/.env file. This means you don't need to set environment variables in your shell or create a separate .env file in the same directory as the docker-compose.yaml file.

Simply make sure your code/.env file contains the necessary environment variables:

AZURE_VECTOR_SEARCH_ENDPOINT=https://your-search.search.windows.net
AZURE_VECTOR_SEARCH_API_KEY=your-api-key
AZURE_OPENAI_ENDPOINT=https://your-openai.azure.com/
AZURE_OPENAI_API_KEY=your-azure-openai-key
OPENAI_API_KEY=your-openai-key

Docker Compose will automatically load these variables from the code/.env file when you run:

docker-compose up -d

⁠Data Persistence with Docker Compose

The docker-compose.yaml file is configured to mount a ./data directory from your host to /app/data in the container. This allows data to persist between container restarts.

⁠Loading Data with Docker Compose

To load data into the knowledge base when using Docker Compose:

docker-compose exec nlweb python -m tools.db_load <url> <name>

For example:

docker-compose exec nlweb python -m tools.db_load https://example.com/rss Example-Wiki

⁠Loading Data with Docker

To load data into the knowledge base when using Docker directly:

docker exec -it <container_id> python -m tools.db_load <url> <name>

For example:

docker exec -it <container_id> python -m tools.db_load https://example.com/rss Example-Wiki

⁠Accessing the Application

Once the container is running, you can access the application at:

http://localhost:8000

⁠Kubernetes Deployment with Helm

NLWeb can be deployed on Kubernetes clusters using the official Helm chart available at iunera/helm-charts⁠.

⁠Quick Installation

# Add the iunera Helm repository
helm repo add iunera https://iunera.github.io/helm-charts/

# Update your Helm repositories
helm repo update

# Install the chart with the release name "my-release"
helm install my-release iunera/nlweb

⁠Features

The Helm chart provides:

• Flexible configuration for deployments, services, and ingress
• Support for environment variables and secrets
• Persistent volume configuration options
• Health monitoring with liveness and readiness probes
• Security context settings with least privilege principles

For detailed configuration options and examples, visit the NLWeb Helm Chart repository⁠.

⁠Installation Guide

For a detailed guide on installing and setting up NLWeb, check out our blog article: NLWeb Enables AI-Powered Websites⁠. The article provides additional context and tips for getting started with NLWeb.

⁠Additional Information

For more detailed information about the NLWeb application, please refer to the main documentation in the repository.