Table of Contents

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>

Ensure Docker is running before proceeding!

Downloading SWIRL Enterprise Files

  1. Locate the email with the subject "Try SWIRL Enterprise".
  2. The email contains three attachments:
    • A PDF with detailed instructions
    • docker-compose.yaml
    • env.license
  3. Save docker-compose.yaml to a folder on the target server.
  4. Rename env.license to .env.license and save it in the same folder.

The leading dot (.) in .env.license is required!

Starting SWIRL Enterprise

  1. Open a command line and navigate to the folder where docker-compose.yaml is saved.

  2. 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:
SWIRL Enterprise Docker successful startup

Verifying SWIRL Startup

  1. Open a new command line and check the running containers:

     docker ps
    

    The output should look like this:
    SWIRL Enterprise Docker ps command

  2. Open a browser and navigate to http://localhost:8000 or http://localhost:8000/galaxy

  3. If the search page loads, click Log Out in the top-right corner. You’ll see the login page:
    SWIRL Login

  4. 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

  5. Enter a search term and press Search. The ranked results should appear:
    SWIRL Results No M365

    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.

  1. Go to http://localhost:8000/swirl/aiproviders/.
  2. Review the pre-loaded AI providers.
  3. To edit a provider, add its ID to the URL. Example:
    http://localhost:8000/swirl/aiproviders/16/

    SWIRL AI Provider

  4. 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).
  5. 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"]
  6. Once an active provider for RAG exists, click Generate AI Insights.
    SWIRL Results with RAG

  7. To access SWIRL AI Search Assistant, visit:
    http://localhost:8000/galaxy/chat

  8. Ask a question, such as:
    “Tell me about SWIRL AI Connect?”

    SWIRL Assistant Conversation with RAG Result

Stopping SWIRL

To stop SWIRL, use one of the following methods:

  1. Via Docker Desktop:
    Shutdown SWIRL with Docker Desktop

  2. Using CTRL+C in the terminal:
    Shutdown SWIRL with Control-C

  3. Via a separate terminal:

docker compose stop

Shutdown SWIRL with docker compose

These methods preserve the SWIRL database. If you don't need to save data, press CTRL+C twice to stop SWIRL instantly.

Optional Steps

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 TBD.
  • 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

  1. Identify your SWIRL Docker container (with app in the name):
    SWIRL docker container app name

  2. Copy the .env file outside Docker:
    SWIRL container env

  3. Stop the containers:
    SWIRL containers stop

  4. Modify docker-compose.yaml:

    Before:
    SWIRL config before

    After:
    SWIRL config after

  5. 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

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