Quick Start Guide - Community Edition

This version applies to the Community Edition of SWIRL!

To run SWIRL in Docker, you must have the latest Docker app for MacOS, Linux, or Windows installed and running locally.
Windows users must first install and configure either the WSL 2 or the Hyper-V backend, as outlined in the System Requirements for installing Docker Desktop on Windows.

Make sure the Docker app is running before proceeding!

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

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

IMPORTANT: To use SWIRL's Real-Time Retrieval Augmented Generation (RAG) in Docker, run the following commands from the Console using a valid OpenAI API key…

For Mac OS or Linux:

export MSAL_CB_PORT=8000
export MSAL_HOST=localhost
export OPENAI_API_KEY=<your-OpenAI-API-key>

For Windows:

set MSAL_CB_PORT=8000
set MSAL_HOST=localhost
set OPENAI_API_KEY=<your-OpenAI-API-key>

Check out OpenAI's YouTube video if you don't have an OpenAI API Key.

On MacOS or Linux, run the following command from the Console:

docker-compose pull && docker-compose up

On Windows, run the following command from PowerShell:

docker compose up

After a few minutes, the following or similar should appear:

app-1    | Start: celery-worker -> celery -A swirl_server worker ... Ok, pid: 55
app-1    | Start: celery-beats -> celery -A swirl_server beat --scheduler django_celery_beat.schedulers:DatabaseScheduler ... Ok, pid: 81
app-1    | Updating .swirl... Ok
app-1    | 
app-1    |   PID TTY          TIME CMD
app-1    |    55 ?        00:00:05 celery
app-1    |    81 ?        00:00:04 celery
app-1    | 
app-1    | setting up logging...
app-1    | setting up logging DONE
app-1    | You're using version 4.0.0.0 of Swirl, the current version.
app-1    | Command successful!
app-1    | INFO 2025-02-17 15:45:00 cli Starting server at tcp:port=8000:interface=0.0.0.0
app-1    | INFO 2025-02-17 15:45:00 server HTTP/2 support not enabled (install the http2 and tls Twisted extras)
app-1    | INFO 2025-02-17 15:45:00 server Configuring endpoint tcp:port=8000:interface=0.0.0.0
app-1    | INFO 2025-02-17 15:45:00 server Listening on TCP address 0.0.0.0:8000

Open this URL with a browser: http://localhost:8000 (or http://localhost:8000/galaxy)

If the search page appears, click Log Out at the top, right. The SWIRL login page will appear:

SWIRL 4.0 Login

Enter the username admin and password password, then click Login.
Enter a search in the search box and press the Search button. Ranked results appear in just a few seconds:

SWIRL AI Connect 4.0 Results

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

As noted above, if using the Community Edition, you must setup OpenAI or Azure/OpenAI prior to executing this step.

SWIRL AI Connect 4.0 Results with RAG

Click the profile avatar in the upper right corner of the Galaxy UI. Then click Manage SWIRL to explore the rest of SWIRL's features.
To view the raw result JSON, click Search under the API section of the Manage SWIRL page linked above, or open http://localhost:8000/swirl/search/

The most recent Search object will be displayed at the top. Click on the result_url link to view the full JSON Response. For example:

SWIRL JSON response

Read the SWIRL User Guide for additional information.
To shut down SWIRL:

Via Docker Desktop:
Press CTRL-C in the terminal window where Docker Compose is running:
Execute docker-compose stop from a different terminal:

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

Notes

SWIRL includes active SearchProviders for Arxiv.org, European PMC and Google News that will work "out of the box" so long as internet access is available. There are also inactive providers for Google Web and SWIRL Documentation that use the Google Programmable Search Engine (PSE). These services require a Google API key. Consult the SearchProvider Guide for more information.

Using SWIRL with Microsoft 365 requires installation and approval by an authorized company Administrator. For more information, please review the M365 Guide or contact support as noted below.