Skip to main content

Installation Guide

Before You Start​

You will need just three things to get the InfoConnect Hybrid Search Engine running:

  1. A computer with Docker support - This is the container system that runs everything
  2. About 10 minutes - Most of this is waiting for downloads to finish
  3. No programming experience required - Just copy and paste the commands
info

Docker is a tool that packages software into containers. Think of it like a shipping container for programs - everything needed to run the app comes bundled inside.

Step 1: Install Docker​

Docker runs all the InfoConnect Hybrid Search Engine services in isolated containers. This keeps everything organized and prevents conflicts with other software on your computer.

Ubuntu/Debian​

Run these commands one at a time in your terminal:

# 1. Remove any old/conflicting packages
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do
  sudo apt-get remove -y $pkg 2>/dev/null || true
done

# 2. Clean up old docker.list if exists
sudo rm -f /etc/apt/sources.list.d/docker.list
sudo rm -f /etc/apt/keyrings/docker.asc

# 3. Fresh install via official repo
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release --codename | cut -f1) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 4. Enable service
sudo systemctl enable --now docker

# 5. Add user to docker group (avoids needing sudo for every command)
sudo usermod -aG docker $USER
Important

After running the commands above, log out and log back in for the permission changes to take effect.

macOS​

Download and install Docker Desktop from the official website: docker.com/products/docker-desktop

Windows​

  1. Download Docker Desktop from docker.com/products/docker-desktop
  2. Run the installer
  3. Follow the prompts to enable WSL 2 (Windows Subsystem for Linux) if asked

Step 2: Install Just (Command Runner)​

Just is a task runner. Think of it like a shortcut menu for commands - instead of typing long, complex commands, you type short, memorable ones like just start or just status.

Ubuntu/Debian​

sudo apt install just

macOS​

brew install just

Windows​

Install via Chocolatey:

choco install just

Or download the binary from github.com/casey/just/releases

Step 3: Start the InfoConnect Hybrid Search Engine​

One command starts everything:

just prod-up

This single command launches:

ServiceWhat It Does
API ServerHandles document uploads and search requests on port 8000
Preprocessing WorkersReads PDFs, Word docs, and other files (worker-preprocessing-1 runs with concurrency 2)
Embedding WorkersConverts text into searchable vectors using AI (2 workers for throughput)
Database (Qdrant)Stores all the document data and search indexes
Task Queue (Redis)Manages background jobs so nothing gets lost
First Startup Takes Longer

The first time you run this, it downloads AI models (about 2-3 minutes). Subsequent starts are much faster.

Optional: Legacy Office formats (.ppt/.xls): To support legacy PowerPoint and Excel files, install LibreOffice and set OFFICE_LEGACY_CONVERSION_ENABLED=true in your .env. These formats are not supported by default.

sudo apt-get install -y libreoffice-headless  # Ubuntu/Debian
brew install --cask libreoffice               # macOS

Step 4: Verify It Is Running​

Check that everything started correctly:

just status

You should see all green checkmarks. Here is what a successful startup looks like:

Container Status:
  api                   running ✅
  worker-preprocessing-1 running ✅
  worker-embedding-1    running ✅
  worker-embedding-2    running ✅
  qdrant               running ✅
  redis                running ✅

Health Checks:
  API Health           ok ✅
  Redis Connection     ok ✅
  Qdrant Connection    ok ✅
tip

Once running, you can access the API documentation at http://localhost:8000/docs

Stop or Reset the System​

Stop but Keep Your Data​

This stops all services but preserves:

  • Your uploaded documents and search index
  • Docker images (for fast restart next time)
just prod-down

Use this during daily development when you plan to start the services again soon.

Stop and Start Fresh​

This stops all services and clears application data:

  • All uploaded documents and search indexes (Qdrant)
  • All task queues and results (Redis)
  • All Docker images (they will be rebuilt on next start)
  • Docker build cache
just prod-down clean

Use this when you want to completely reset the system, free up disk space, or if something is not working and you want to start over. Note that the next just prod-up will take longer because it needs to rebuild the Docker images.

Common Problems​

ProblemCauseSolution
Port 8000 already in useAnother application is using port 8000Stop the other app, or change the port by editing the .env file
Permission denied when running Docker commandsYour user is not in the docker groupRun: sudo usermod -aG docker $USER then log out and back in
Services show as "unhealthy"Services are still starting upWait 30 seconds and run just status again
Cannot connect to Docker daemonDocker is not runningStart Docker Desktop (macOS/Windows) or run sudo systemctl start docker (Linux)
First startup seems stuckDownloading AI models takes timeWait 2-3 minutes for the model downloads to complete
just command not foundJust is not installed or not in your PATHReinstall Just and restart your terminal

What's Next​

Now that the InfoConnect Hybrid Search Engine is running, here is what you can do next: