Quick Start Guide

1. Prerequisites

• To run SWIRL in Docker, install the latest Docker app for macOS, Linux, or Windows.
• Windows users: install and configure WSL 2 or Hyper-V first, as outlined in the Docker Desktop system requirements.

2. Download and Start SWIRL

1. Download the Docker Compose file

curl https://raw.githubusercontent.com/swirlai/swirl-search/main/docker-compose.yaml -o docker-compose.yaml

2. Set Up Environment Variables

To enable real-time Retrieval-Augmented Generation (RAG) in SWIRL, export the following environment variables.

MSAL values for SWIRL's host and port

MacOS or Linux:

export MSAL_CB_PORT=8000
export MSAL_HOST=localhost

Windows (PowerShell):

$Env:MSAL_CB_PORT = "8000"
$Env:MSAL_HOST = "localhost"

Valid model version along with valid OpenAI or Azure/OpenAI credentials

MacOS or Linux:

export SWIRL_RAG_MODEL='gpt-4.1'

export OPENAI_API_KEY=<your-OpenAI-API-key>

export AZURE_OPENAI_KEY=<your-AzureOpenAI-key>
export AZURE_OPENAI_ENDPOINT=<your-AzureOpenAI-endpoint>
export AZURE_MODEL='gpt-4.1'
export AZURE_API_VERSION=<your-AzureOpenAI-version>

Windows (PowerShell):

$Env:SWIRL_RAG_MODEL = "gpt-4.1"

$Env:OPENAI_API_KEY = "<your-OpenAI-API-key>"

$Env:AZURE_OPENAI_KEY = "<your-AzureOpenAI-key>"
$Env:AZURE_OPENAI_ENDPOINT = "<your-AzureOpenAI-endpoint>"
$Env:AZURE_MODEL = "gpt-4.1"
$Env:AZURE_API_VERSION = "<your-AzureOpenAI-version>"

3. Start SWIRL

For macOS or Linux:

docker compose pull && docker compose up

For Windows (PowerShell):

docker compose up

After a few minutes, you should see output similar to:

app-1    | Start: celery-worker -> celery -A swirl_server worker ... Ok, pid: 55
app-1    | INFO 2025-02-17 15:45:00 server Listening on TCP address 0.0.0.0:8000

3. Access the SWIRL Interface

• Open http://localhost:8000 (or http://localhost:8000/galaxy) in your browser.
• If the search page appears, click Log Out at the top-right corner. The SWIRL login page will load:

• Login credentials:
• Username: admin

• Password: password

• Enter a search query in the search box and click Search. Ranked results should appear within a few seconds:

4. Generate AI Insights

• Click the Generate AI Insight button to apply RAG using the most relevant results.

5. Managing SWIRL

• Click the profile avatar in the upper-right corner of the Galaxy UI.
• Select Manage SWIRL to explore additional features.
• To view raw search results in JSON format:
• Go to http://localhost:8000/swirl/search/.
• Click the result_url link to view the full JSON response.

6. Shutting Down SWIRL

You can stop SWIRL in several ways:

1. Using Docker Desktop:
   

2. Using Terminal (CTRL+C):
   

3. Using Docker Compose (from a new terminal window):

   docker compose stop

Notes

These work out of the box as long as internet access is available.