SWIRL Docs
/
swirlaiconnect.com
Enterprise Edition

Installation Guide

This guide covers installing SWIRL 5 Enterprise with Docker Compose - the recommended deployment for SWIRL 5 - plus pointers for Community installs and Kubernetes.

Prerequisites

  • A host meeting the system requirements (32 cores / 64 GB recommended).
  • Docker Engine (or Docker Desktop) with the Compose plugin.
  • A SWIRL Enterprise license (signed JSON) and image access - contact SWIRL.
  • Outbound network access for the sources you plan to search and the AI providers you plan to use.

The Compose Stack

SWIRL 5 Enterprise runs as a set of cooperating containers (see the service table in the Quick Start). Two of them matter for understanding startup:

  • swirl-init runs on every docker compose up and exits when done. On a fresh database it creates the schema and loads seed data (branding, authenticators, SearchProviders, AI providers, prompts, pipelines); on an existing database it applies any pending migrations but does not re-load seed data. It also provisions the API token used by the MCP sidecar.
  • swirl collects static files, initializes the vector store (Qdrant collections) and the cache storage bucket, starts the task workers, and serves the application on port 8000.

Seed data loads only on a fresh database. When swirl-init finds an existing database it applies pending migrations but skips seeding. To re-seed from scratch, run docker compose down -v (this deletes all data) before docker compose up -d.

Configuration (.env)

All deployment configuration lives in the .env file next to the compose file. Key variables:

Variable Purpose
SWIRL_LICENSE The signed license JSON: SWIRL_LICENSE=<license-json>. Search, chat, and the Semantic Cache are gated on it.
ADMIN_PASSWORD Password for the admin superuser, created by the one-time setup job
SECRET_KEY Django secret key - recommended for production; generate a unique value per deployment
ALLOWED_HOSTS, SWIRL_FQDN, PROTOCOL, SWIRL_PORT Hostname and URL settings
SQL_ENGINE, SQL_DATABASE, SQL_USER, SQL_PASSWORD, SQL_HOST, SQL_PORT PostgreSQL connection (defaults target the stack's postgres service)
CELERY_BROKER_URL, CELERY_RESULT_BACKEND, CACHE_REDIS_URL Redis connections
SWIRL_QDRANT_MODE, SWIRL_QDRANT_URL Vector store for the Semantic Cache (docker mode targets the stack's qdrant service)
SWIRL_STORAGE_* Object storage for cached document bodies (defaults target the stack's seaweedfs service)
TIKA_SERVER_ENDPOINT Text-extraction service (defaults to the stack's tika service)
SWIRL_OLLAMA_URL Optional local LLM service
MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_REDIRECT_URI Microsoft 365 integration (see the M365 Guide)
SWIRL_MCP_* MCP server settings (see the MCP guide)

Semantic Cache tuning variables are documented in the Semantic Cache Guide. Never commit .env, license files, or credentials to version control; use placeholders such as <api-key> and <client-secret> in any shared copies.

Install and First Start

# 1. clone github.com/swirlai/docker-compose (or unpack the compose bundle)
# 2. copy env.example to .env and set SWIRL_LICENSE, ADMIN_PASSWORD, SQL_USER, SQL_PASSWORD
docker compose pull
docker compose up -d
docker compose logs -f swirl-init   # watch one-time DB setup complete

Then verify the deployment as described in Verifying SWIRL Startup - log in as admin with the ADMIN_PASSWORD you set. For a production VM with systemd and TLS ingress, follow the repository's Production Deployment guide. If startup fails, check the logs (see Viewing Logs) and the Troubleshooting Guide.

Upgrading

# back up the database first (see the Admin Guide)
docker compose pull
docker compose up -d
  • Database migrations apply automatically during startup.
  • Volumes (pg_data, qdrant_data, seaweed_data) persist across upgrades; do not use down -v during an upgrade.
  • Upgrading from SWIRL 4.x to SWIRL 5: request the upgrade runbook from support - a new license is required, and the Semantic Cache entitlement (cache) is opt-in.

Securing a SWIRL Enterprise Deployment

Before exposing SWIRL Enterprise to end users, review the Security Guide for the full production hardening checklist (TLS termination at the reverse proxy, secret management, OIDC/SSO setup, PII redaction, network egress controls, and logging). In particular:

  • Terminate TLS at a reverse proxy in front of port 8000.
  • Do not publish the MCP sidecar's port beyond localhost/private networks in static-token mode - see MCP client-side authentication.
  • Use a strong ADMIN_PASSWORD and create per-user accounts or SSO.