Installation Guide

System Requirements

• Platform: Ubuntu, RHEL, or macOS. Microsoft Windows is not supported due to Celery dependencies.
• Hardware: 8+ vCPU, 16+ GB RAM.
• Storage: 500+ GB free disk space.
• Python: 3.12 or newer (3.13 is the tested version).

macOS

• Python 3.12+ with pip.
  • Ensure Python runs as python, not python3.
  • Optional: install venv or pyenv.
• Homebrew installed and updated.
• Redis:

  brew install redis

• jq:

  brew install jq

Linux

• Python 3.12+ with pip.
• Redis and jq:

  sudo apt install jq redis-server -y

PostgreSQL (optional)

To use PostgreSQL as a data source or SWIRL's backend database:

1. Install PostgreSQL.
2. Ensure pg_config is in your system PATH.
3. Install the PostgreSQL driver:

   pip install psycopg2

Installing SWIRL AI Search

1. Clone the repository:

   git clone https://github.com/swirlai/swirl-search
   cd swirl-search

2. Install SWIRL (macOS):

   ./install.sh

3. Install SWIRL (Linux):

   apt-get update --allow-insecure-repositories -y && apt-get install apt-file -y && apt-file update && apt-get install -y python3-dev build-essential
   ./install.sh

4. If install.sh fails, install manually:

   pip install -r requirements.txt
   python -m spacy download en_core_web_lg
   python -m nltk.downloader stopwords
   python -m nltk.downloader punkt_tab

Setup SWIRL

Initialize SWIRL:

python swirl.py setup

Setup RAG

To enable real-time Retrieval-Augmented Generation (RAG):

export MSAL_CB_PORT=8000
export MSAL_HOST=localhost

See the RAG Configuration Guide for more details.

Install the Galaxy UI

With Docker running:

./install-ui.sh

Start SWIRL

To start SWIRL:

python swirl.py start

Open the SWIRL Homepage

Visit http://localhost:8000/swirl/:

Open the Galaxy UI

Visit http://localhost:8000 or http://localhost:8000/galaxy/.

If the search page loads, log out to see the login screen:

Log in to SWIRL

• Username: admin
• Password: password

Perform a Search

1. Enter a search query in the search box.
2. Click Search.
3. Results appear in seconds:

Enable RAG (if OpenAI API key is set)

Click Generate AI Insight:

Manage SWIRL

Click the profile avatar (top-right), then click Manage SWIRL.

View Raw JSON Results

• Click Search under API in the Manage SWIRL page.
• Open http://localhost:8000/swirl/search/.
• Click result_url to view the full JSON response:

Read More

See the SWIRL User Guide for additional details.