Table of Contents

System Requirements

Installation Guide
Community Edition

SWIRL no longer starts Redis automatically.
You must have Redis installed and running before starting SWIRL.
Refer to Install Redis for details.

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.11 or newer

macOS

Python 3.12+ with pip
- Ensure Python runs as python, not python3
- Install venv (optional)
- Install pyenv (optional)
Homebrew installed and updated
Redis installed:
```
brew install redis
```
jq installed:
```
brew install jq
```

Linux

Python 3.12+ with pip
Redis and jq installed:
```
sudo apt install jq redis-server -y
```

PostgreSQL (optional)

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

Install PostgreSQL
Ensure pg_config is in your system PATH
Install the PostgreSQL driver:
```
pip install psycopg2
```

Installing SWIRL AI Search

Clone the repository:

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

Install SWIRL (macOS):
```
./install.sh
```

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

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

macOS SSL Issues? See: urllib and "SSL: CERTIFICATE_VERIFY_FAILED" Error

Setup SWIRL

Run the following command to 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

To install Galaxy UI, you must have the latest Docker installed and running.

Run the following command with Docker running:

./install-ui.sh

Galaxy UI must be installed only after running ./install.sh and python swirl.py setup.

Start SWIRL

To start SWIRL, run:

python swirl.py start

Open the SWIRL Homepage

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

SWIRL Homepage

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:

SWIRL Login

Log in to SWIRL

Username: admin
Password: password

Perform a Search

Enter a search query in the search box.
Click Search.
Results will appear in seconds:

SWIRL Results

Enable RAG (if OpenAI API key is set)

Click Generate AI Insight:

SWIRL Results with RAG

Manage SWIRL

Click the profile avatar (top-right) → 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:

Refer to the SWIRL User Guide for additional details.