Advanced topics

AI service (on-premise)

This guide installs the Jitbit AI service next to your on-premise HelpDesk. It enables AI features like similar-article suggestions and knowledge-base search, powered by a small Docker stack that runs on your own network.

Paid add-on. The on-premise AI service is a licensed add-on to your HelpDesk installation, sold separately from the core product. See the product page for pricing and licensing.

Requirements

  • Jitbit HelpDesk v11.22 or newer. The AI-service admin UI and on-prem integration hooks were added in 11.22 — earlier versions can't talk to the service.
  • Docker Desktop (Windows) or Docker Engine (Linux), version 20.10 or newer.
  • 4 GB free RAM (2 GB for Qdrant, ~1.5 GB for embedding models).
  • Internet access on the server — required to pull the Qdrant image, download embedding models on first run, and (optionally) reach OpenAI.
  • An open TCP port (default 5050) reachable from your HelpDesk web server.

1. Download the release bundle

Download jitbit_ai.zip using the secure download link in your license email. Unzip it on the server where you want the AI service to run:

unzip jitbit_ai.zip
cd jitbit_ai

The bundle contains:

  • ai.py, config.py, requirements.txt, Dockerfile, .dockerignore — Python source + container recipe. Docker builds the image locally on first startup; no image needs to be pulled from a registry.
  • templates/ — the status-page template served by the AI container.
  • docker-compose.yml — two-service stack (AI service + Qdrant).
  • .env.example — template for your secrets.
  • VERSION / version.txt — the release version of this bundle.
  • README.txt — a copy of this guide.

2. Create the .env file

cp .env.example .env

Edit .env and fill in:

AI_API_KEY=<paste a random 48-character hex string here>
OPENAI_API_KEY=<your OpenAI key, or leave blank>

AI_API_KEY is a shared secret you make up — it authenticates HelpDesk to this service and nothing else. It is not your Jitbit license key: pick any random value, and paste the same one into HelpDesk in step 4.

To generate a random AI_API_KEY value:

  • Come up with it yourself OR
  • Linux / macOS: openssl rand -hex 24
  • Windows PowerShell: -join (1..48 | % { '0123456789abcdef'[(Get-Random -Maximum 16)] })

Leave OPENAI_API_KEY blank if you want to use only local embedding models. You can change this later by editing .env and running docker compose up -d again — but note that switching between local models and OpenAI changes the embedding dimensions, so you'll need to re-index your knowledge base afterwards (see step 5).

3. Start the service

docker compose up -d

First startup takes several minutes:

  1. Docker builds the AI image locally (pip install runs inside the build — ~1 minute).
  2. Docker pulls the Qdrant image from Docker Hub (~200 MB).
  3. On first request, the AI container downloads ~300 MB of embedding model weights from Hugging Face into the fastembed_cache volume.

Subsequent restarts are fast — everything's cached.

Verify both containers are healthy:

docker compose ps

Both should report running.

Verify the service is configured correctly — open http://localhost:5050/ in a browser. The page shows a table of checks (Qdrant connection, embedding model cache, OpenAI configuration, indexed data) and should all be green. No login required.

For automated monitoring, GET /healthz returns a JSON health snapshot and HTTP 503 if Qdrant is unreachable. This endpoint requires the x-api-key header (same value as AI_API_KEY); unauthenticated requests get 401.

4. Point HelpDesk at the service

In HelpDesk, sign in as an admin and open Administration → AI features. Under Self-hosted AI service, set:

  • Service URL: http://<ai-host>:5050
  • API Key: the same value you put in AI_API_KEY in .env.

Replace <ai-host> with localhost if you're running AI on the same server as HelpDesk, or the LAN hostname/IP otherwise. Click Save — no app pool recycle needed.

Upgrading from an earlier release? If you previously set AIUrl/AIKey directly in appsettings.json, those values continue to work as a fallback. We recommend moving the configuration to the UI so it survives future upgrades.

5. Index your knowledge base

The first time you save the service URL in HelpDesk, indexing starts automatically — HelpDesk queues every knowledge-base article and sends it to the AI service in the background. There's nothing else to click.

Indexing runs in batches (up to a few hundred articles every 15 minutes), so a large knowledge base can take a while to finish. Watch progress on the status page at http://<ai-host>:5050/ — the Indexed data row shows the vector count climbing as articles are processed. Similar-article suggestions and KB search begin working for each article as soon as it's indexed.

After the initial load, re-indexing happens automatically whenever you add or edit an article. To force a full re-index, re-save the service settings in Administration → AI features.

Security & network

The service has no built-in transport encryption, and the status page at / is intentionally reachable without the API key (it exposes only aggregate health — no keys, no article content). Treat the AI service as an internal component:

  • Keep it on a trusted network. Don't expose port 5050 to the public internet — restrict it with a firewall so that only your HelpDesk server can reach it.
  • The x-api-key travels in clear text over http://. If HelpDesk and the AI service sit on different hosts across an untrusted network, put the service behind a TLS-terminating reverse proxy and point HelpDesk at the https:// URL.

Backups

All indexed data lives in the qdrant_storage Docker volume (cached models live in fastembed_cache). To back it up, stop the stack with docker compose down and archive the volumes. Backups are optional, though — the index is fully reproducible from your HelpDesk knowledge base at any time by re-saving the settings in Administration → AI features (see step 5).

Upgrading

  1. Download the new jitbit_ai.zip from the same secure download link.
  2. Unzip into a fresh directory (keep the old one around in case you need to roll back).
  3. Copy your existing .env into the new directory.
  4. Stop the old stack: in the old directory, docker compose down (volumes are preserved — they live in Docker, not in the unzipped folder).
  5. In the new directory: docker compose up -d --build.

Both containers come up against the existing qdrant_storage and fastembed_cache volumes, so indexed data and cached models carry over.

Check release notes before upgrading between major versions — some releases may require re-indexing after a Qdrant schema change.

Troubleshooting

docker compose ps shows jitbit-ai restarting. Check logs: docker compose logs jitbit-ai. Most common cause: missing AI_API_KEY in .env.

Port 5050 already in use on the host. Edit docker-compose.yml and change "5050:5000" to any free port, e.g. "8080:5000". Update the Service URL in Administration → AI features to match.

HelpDesk returns no similar articles. Open http://<ai-host>:5050/ in a browser from the HelpDesk server. If the page loads but shows Qdrant as unreachable, the AI container lost its database connection — docker compose restart jitbit-ai. If the page doesn't load at all, it's a network / firewall issue. If the page is healthy but the Indexed data count is still zero or low, indexing may simply still be in progress (see step 5) — give it time on a large knowledge base.

High memory usage. The AI container uses ~500 MB per gunicorn worker. Reduce GUNICORN_WORKERS in .env to 1 if the server is memory-constrained.

pip install fails during build. You don't have internet access or your network blocks PyPI. The bundle requires internet at build time.

Uninstalling

Stop and remove the stack along with its data:

docker compose down -v

Then clear the Service URL in Administration → AI features so HelpDesk stops calling the service.

Previous
Self-hosted installation
Next
API reference