Table of Contents
- Downloading SWIRL Enterprise Files
- Starting SWIRL Enterprise
- Verifying SWIRL Startup
- Enabling AI Features
- Stopping SWIRL
- Optional Steps
- Microsoft 365 Integration
- Google Workspace Integration
- Persisting Configuration Changes
- Running SWIRL Commands
- Migrating from SWIRL Community
- Updating SWIRL
- Recommended Cloud Instances
Quick Start Guide
Enterprise Edition
Please contact SWIRL for access to SWIRL Enterprise.
Please note: we've renamed our products! SWIRL AI Connect is now SWIRL AI Search 🔎 and SWIRL AI Co-Pilot is now SWIRL AI Search Assistant 🤖
-
The recommended minimum system configuration is a 32-core server, with 64 GB of memory and at least 500 GB of available disk space. This configuration supports up to 25 users. View recommended cloud instances for AWS, Azure and GCP.
-
To run SWIRL in Docker, install the latest version of Docker for macOS, Linux, or Windows. Ensure Docker is configured to use all available CPU, memory, and storage.
-
You must be logged in to Docker Hub. Open a command-line interface (CLI) and execute the following command, replacing
<docker-username>
and<docker-password>
with your credentials:
docker login --username <docker-username> --password <docker-password>
- Windows users must install and configure either WSL 2 or the Hyper-V backend, as outlined in the Docker Desktop System Requirements.
Ensure Docker is running before proceeding!
Downloading SWIRL Enterprise Files
- Locate the email with the subject "Try SWIRL Enterprise".
- The email contains three attachments:
- A PDF with detailed instructions
docker-compose.yaml
env.license
- Save
docker-compose.yaml
to a folder on the target server. - Rename
env.license
to.env.license
and save it in the same folder.
The leading dot (.
) in .env.license
is required!
Starting SWIRL Enterprise
-
Open a command line and navigate to the folder where
docker-compose.yaml
is saved. -
Run the following commands to pull and start the containers:
docker compose up -d
docker compose logs -f app
Do not press CTRL+C or stop Docker during this process—doing so will shut down SWIRL.
This starts all required SWIRL services and displays the log output. Initialization takes a few minutes and completes successfully when you see the message Server Listening on...
.
Press CTRL+C to stop the log output.
NOTE TO EDITORS: verify that the below screenshot is still current.
Once complete, the output should look like this:
Verifying SWIRL Startup
-
Open a new command line and check the running containers:
docker ps
The output should look like this:
-
Open a browser and navigate to http://localhost:8000 or http://localhost:8000/galaxy
-
If the search page loads, click
Log Out
in the top-right corner. You’ll see the login page:
-
Log in with:
- Username:
admin
- Password:
password
If you receive a warning about the password being compromised, follow these steps:
Change the super user password - Username:
-
Enter a search term and press
Search
. The ranked results should appear:
If no results appear or an error occurs, please contact support.
Enabling AI Features
To use Generate AI Insights (RAG) or AI Search Assistant, at least one AI provider must be activated.
- Go to http://localhost:8000/swirl/aiproviders/.
- Review the pre-loaded AI providers.
-
To edit a provider, add its ID to the URL. Example:
http://localhost:8000/swirl/aiproviders/16/ -
Use the "Raw Data" form at the bottom to make changes, then click PUT to save.
To function correctly, an AI provider must:
- Have
"active": true
set. - Include
"rag"
and/or"chat"
in the"tags"
list. - Include
"rag"
and/or"chat"
in the"defaults"
list. - Have a valid API key (if required).
- Have
-
To create a new provider, copy an existing one and paste it as a new entry.
To use different AI providers for RAG and AI Search Assistant, adjust the
"defaults"
list:- Example:
- OpenAI GPT-4 →
"defaults": ["rag"]
- Azure/OpenAI GPT-4o →
"defaults": ["chat"]
- OpenAI GPT-4 →
- Example:
-
Once an active provider for RAG exists, click Generate AI Insights.
-
To access SWIRL AI Search Assistant, visit:
http://localhost:8000/galaxy/chat -
Ask a question, such as:
“Tell me about SWIRL AI Connect?”
Stopping SWIRL
To stop SWIRL, use one of the following methods:
-
Via Docker Desktop:
-
Using CTRL+C in the terminal:
-
Via a separate terminal:
docker compose stop
These methods preserve the SWIRL database. If you don't need to save data, press CTRL+C twice to stop SWIRL instantly.
Optional Steps
- Customize SWIRL for any organization
- Upload a branding configuration including logos and Galaxy control labels
- Customize the AI Search RAG prompt and the AI Search Assistant prompt
- Manage SWIRL via Galaxy UI:
- Click the profile avatar (top-right corner).
- Click Manage SWIRL (http://localhost:8000/swirl/).
Microsoft 365 Integration
To connect SWIRL with Microsoft 365, you need:
- Admin access to the Azure/M365 tenant.
- App registration in Azure.
- App ID and secrets added to SWIRL.
Setup takes ~1 hour. Follow the guide: Microsoft 365 Integration Guide
For additional support, please contact SWIRL.
Google Workspace Integration
To connect SWIRL with Google Workspace, you need:
- Admin access to the Google Workspace tenant.
- App registration in Google Workspace.
- App ID and secrets added to SWIRL.
Setup takes ~1 hour. Follow the guide: Google Workspace Integration Guide
For additional support, please contact SWIRL.
Persisting Configuration Changes
-
Identify your SWIRL Docker container (with
app
in the name):
-
Copy the
.env
file outside Docker:
-
Stop the containers:
-
Modify
docker-compose.yaml
:Before:
After:
-
Restart SWIRL:
docker compose pull && docker compose up
Running SWIRL Commands
Use the following sequence to run Django or SWIRL commands:
APP_CID=$(docker ps -q -f name=app)
docker exec -it $APP_CID /bin/bash
Then run:
python manage.py <django-command>
or
python swirl.py <swirl-command>
Example: python manage.py makemigrations
Migrating from SWIRL Community
Migrating SearchProviders
Before migrating, consider deleting the preloaded SearchProviders in the SWIRL Enterprise installation.
-
Locate the
migrate_sp.py
script. As of SWIRL 4.4, this is located in theDevUtils
folder. If you are running an earlier version please request it from support -
Go to the
swirl/SearchProviders
endpoint on the SWIRL server. Copy the entire JSON list to the clipboard, then paste this into a text file. Save the text file - for example, tomySPs.json
-
Run the script:
python migrate_sp.py myCommunitySPs.json myEnterpriseSPs.json
-
Open the output file. Copy and paste the contents into the input box at the bottom of the same endpoint
/swirl/SearchProviders
of your SWIRL Enterprise installation. Click thePUT
button. -
The page should refresh and show you the new SearchProviders. (If there were already SearchProviders loaded, the new ones will be later in the list.)
Note any errors, and feel free to contact support for assistance.
Migrating OpenAI/Azure OpenAI settings
- Go to the
/swirl/aiproviders/
endpoint in the SWIRL Enterprise installation.
-
Locate the OpenAI or AzureOpenAI preloaded configuration.
-
Copy the API key from the Community
.env
file, or the appropriate environment variable, to thecredentials
field in the Enterprise AI Provider. For example:
For OpenAI:
% echo $OPENAI_API_KEY
<your-key-here>
For Azure/OpenAI:
% echo $AZURE_OPENAI_KEY
<your-api-key>
% echo $AZURE_OPENAI_ENDPOINT
<your-azure-openai-endpoint-url>
% echo $AZURE_MODEL
<your-azure-openai-model>
Set the Enterprise AI Provider configuration active
to true
. Set the tags
and default
lists to include rag
and chat
.
- Refresh the Galaxy UI. The
Generate AI Insights
switch in the Galaxy Search UI should now be available, and theSWIRL AI Assistant
(at/galaxy/chat
), or use the link under the profile icon (top/right).
Migrating M365 Authentication
-
Go to the
swirl/authenticators/Microsoft
endpoint in the SWIRL Enterprise installation. -
Copy the
Client Id
andClient Secret
from the M365 Azure App Registration or your Community.env
file as noted here in the Microsoft 365 Integration Guide.
Note that you may have to modify the existing app registration if URL of the SWIRL server is changing.
Updating SWIRL
Be sure to complete all steps under Persisting Configuration Changes before upgrading.
Use the following commands to update SWIRL:
docker compose pull
docker compose stop
docker compose up -d
Then monitor the logs:
docker compose logs -f app
Once SWIRL has restarted, run:
python swirl.py reload_ai_prompts
python manage.py load_authenticators swirl/fixtures/DefaultAuthenticators.json
If this release includes updates to any SearchProvider used in your setup, update it:
python manage.py load_fixture SearchProviders/<searchprovider-name>
Refer to Running SWIRL Commands above for details.
To confirm the upgrade, repeat the Verifying SWIRL Startup steps.
Recommended Cloud Instances
Cloud Platform | Instance / Machine Type | vCPUs | RAM | Default / Local Storage |
---|---|---|---|---|
AWS EC2 | c6i.8xlarge | 32 | 64 GiB | EBS-only |
c7g.8xlarge | 32 | 64 GiB | EBS-only | |
GCP Compute Engine | n2-custom-32-65536 | 32 | 64 GB | None (customizable) |
c2d-standard-32 | 32 | 128 GB | None (customizable) | |
Azure VMs | Standard_F32s_v2 | 32 | 64 GiB | OS disk only |