Community Edition

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.

Ensure that the Docker app is running before proceeding!

2. Download and Start SWIRL

Download the Docker Compose file

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

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>"

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 you land on a search page, click your profile avatar → Log Out first; this returns you to the SWIRL login.

Login credentials:
Username: admin
Password: password

After signing in, the new SWIRL Galaxy home page appears, with a single search bar, recent searches, suggested-source chips, and a 14-day search activity sparkline:

SWIRL Galaxy home page

Enter a search query in the search box and click Search. Ranked results — and, if RAG is enabled, an AI Summary at the top — appear within a few seconds:

SWIRL Galaxy results with AI Summary

4. Generate AI Insights

Click the + Generate button below the search bar (or the Generate AI Insight button on a results page) to apply RAG to the most relevant results.

Important: SWIRL Community ships preloaded with OpenAI and Azure/OpenAI AIProvider records — but you still need to set OPENAI_API_KEY (or Azure equivalents) for the call to succeed. As of Community 4.5 you can also paste the key directly into the AIProvider record from the Administration Console at /admin/swirl/aiprovider/.

SWIRL AI Summary in results

5. Managing SWIRL

COMMUNITY: The standalone /swirl/ dashboard has been replaced by the new Administration Console at http://localhost:8000/admin/. From the Administration Console you can:

Add and edit SearchProviders, AIProviders, and Query Transforms without touching .env or JSON fixtures.
Open the Log Viewer to tail Django and Celery logs.
Open Activity Analytics to inspect search volume, top providers, and futile queries.
Manage users, groups, API tokens, and OAuth tokens.

To view raw search results in JSON format, use the browsable REST API at http://localhost:8000/swirl/search/ and click the result_url link on any search record. For the full schema, see Swagger / OpenAPI.

{
  "messages": [
    "SWIRL AI COMMUNITY 4.5.0.2",
    "[2026-05-20 11:38:04.559113] Retrieved 10 of 100 results from: News - Google News",
    "[2026-05-20 11:38:04.974641] Retrieved 10 of 5187 results from: Articles - EuropePMC",
    "[2026-05-20 11:38:05.507881] Retrieved 10 of 1449 results from: Web - Internet Archive",
    "[2026-05-20 11:44:25.983136] Results ordered by: RelevancyMixer"
  ],
  "info": {
    "results": {
      "found_total": 6727,
      "retrieved_total": 30,
      "retrieved": 10,
      "federation_time": 10.8,
      "result_blocks": [
        "ai_summary"
      ],
      "next_page": "http://localhost:8000/swirl/results/?search_id=9&page=2"
    },
    "Web - Internet Archive": {
      "found": 1449,
      "retrieved": 10,
      "filter_url": "http://localhost:8000/swirl/results/?search_id=9&provider=4",
      "query_string_to_provider": "cybersecurity policy",
      "search_time": 3.6
    },
    "Articles - EuropePMC": {
      "found": 5187,
      "retrieved": 10,
      "filter_url": "http://localhost:8000/swirl/results/?search_id=9&provider=5",
      "query_string_to_provider": "cybersecurity policy",
      "search_time": 3.2
    },
    "News - Google News": {
      "found": 100,
      "retrieved": 10,
      "filter_url": "http://localhost:8000/swirl/results/?search_id=9&provider=2",
      "query_string_to_provider": "cybersecurity policy",
      "search_time": 2.0
    }
  },
  "results": [
    {
      "swirl_rank": 1,
      "swirl_score": 24911.43237469431,
      "searchprovider": "News - Google News",
      "searchprovider_rank": 5,
      "title": "Maryland unveils statewide zero-trust <em>cybersecurity</em> <em>policy</em> - StateScoop",
      "url": "https://news.google.com/rss/articles/CBMijgFBVV95cUxOR2VDaEJaU1ZVNzg4Xzc3SGZkTkV3MEFrblFZTExJcXh1OWN...",
      "body": "Maryland unveils statewide zero-trust <em>cybersecurity</em> <em>policy</em> StateScoop...",
      "date_published": "2026-02-24 08:00:00+00:00",
      "author": "StateScoop",
      "swirl_id": 5
    },
    {
      "swirl_rank": 9,
      "swirl_score": 5750.152160674617,
      "searchprovider": "Articles - EuropePMC",
      "searchprovider_rank": 1,
      "title": "<em>Cybersecurity</em> <em>policy</em> framework requirements for the establishment of highly interoperable and intercon",
      "url": "https://europepmc.org/article/MED/38784226",
      "body": "This paper examines <em>cybersecurity</em> <em>policy</em> framework requirements for establishing highly interoperable and interconnected health data spaces, w...",
      "date_published": "2024-01-01 00:00:00",
      "author": "Luidold C, Jungbauer C.",
      "swirl_id": 11
    }
  ],
  "ai_summary": []
}

6. Shutting Down SWIRL

You can stop SWIRL in several ways:

Using Docker Desktop:
Using Terminal (CTRL+C):
Using Docker Compose (from a new terminal window):

   docker compose stop

Shutdown SWIRL with docker compose

The Docker version of SWIRL Community does not retain any data or configuration when shut down.

Notes

Pre-configured SearchProviders. SWIRL ships with active SearchProviders for: - Arxiv.org — default; included in all searches. - European PMC — active but not default; use the tag: syntax or add to searchprovider_list to include. - Google News — default; included in all searches.

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

The Web - Google PSE and Docs - SWIRL SearchProviders are inactive by default and require your own Google credentials. SWIRL does not ship a Google API key — Google's Custom Search API is billed against whichever account owns the key, so every install must supply its own. You will need both a Google API key (from Google Cloud Console) and a Programmable Search Engine ID (from programmablesearchengine.google.com). Paste both into the SearchProvider record at Admin Console → SearchProviders — the full walkthrough is in the SearchProvider Guide.

Using SWIRL with Microsoft 365 requires installation and approval by an authorized company administrator. See the M365 Guide or contact support.