This guide covers both Free and Pro editions in one place. Where a feature is Pro-only, it is marked (Pro).

1. Installation

1.1 Requirements

Node.js 18+ - Required runtime to run the chatbot backend server.
npm - Required to install project dependencies.
Modern browser - Required to access admin panel and test widget behavior.
PostgreSQL 13+ (Pro optional) - Required only if you choose PostgreSQL storage mode.
pgvector (Pro optional) - Required for PostgreSQL vector similarity search in RAG mode.
Ollama (Pro optional) - Required only if you want local embedding generation with zero API cost.

1.2 Download and Prepare

Extract package - Unzip either stella-ai-chatbot-free or stella-ai-chatbot-pro.
Open folder in terminal - Run all install/start commands from this directory.
Install dependencies - Downloads all required backend libraries.

npm install

1.3 Configure Environment

Create .env - Copy .env.example to .env.
Set required variables:
- NODE_ENV - Defines runtime mode (development or production).
- APP_SECRET - Used to sign/verify secure tokens and sessions.
- ADMIN_USER - Admin login username.
- ADMIN_PASS - Admin login password.
- INSTALL_TOKEN - Protects installer from unauthorized access.
- CORS_ORIGINS / ALLOWED_ORIGINS - Controls which origins can call APIs.
- DATA_ENCRYPTION_KEY - Used for encryption of sensitive data (if supported in your edition).
Optional variables:
- PORT - Server port (platform can override dynamically).
- TRUST_PROXY=true - Enable correct IP detection behind reverse proxy/CDN.

1.4 Start Application

npm start

/install - First-time setup wizard.
/admin - Admin login and dashboard.

1.5 Installer Steps

Open installer - /install Initializes chatbot system.
Enter install token - Confirms authorized installation.
Select storage mode:
- Free: JSON storage.
- Pro: JSON or PostgreSQL.
Complete install - Creates required defaults/settings.
install.lock generated - Prevents accidental reinstallation and it is present in the data folder.

1.6 Embed Widget on Any Website

Open Embed Code section - Generates script for frontend integration.
Copy script - Includes widget loader and API base URL.
Paste before </body> - Ensures widget loads after page content.
Refresh site - Verifies chatbot appears and works.

1.7 Production Checklist

Enable HTTPS - Protects traffic and credentials.
Use strong secrets - Prevents token/session compromise.
Restrict domains - Prevents widget/API misuse on unauthorized sites.
Protect installer - Blocks public reinstall attacks.
Enable CSRF/security controls - Protects admin write actions.
Set retention policy - Keeps logs manageable and compliant.

2. User Guide (Step-by-Step)

2.1 Admin Login

Open /admin - Access admin entry page.
Sign in - Uses credentials from .env.
Navigate menu - Overview, Settings, FAQs, Logs.

2.2 Overview Page

Usage stats - Shows chatbot activity summary.
Matched vs unmatched - Shows answer quality trend.
Top matched keywords - Identifies what users ask successfully.
Top unmatched questions - Shows FAQ/AI content gaps to improve.

2.3 Settings Page

A. Core Identity

Chatbot Name - Display title shown in the chat header.
Avatar Upload - Brand image shown in widget launcher and chat.
Avatar Shape - Controls whether avatar appears round or square.
Show Live Preview - Toggles real-time preview in admin settings page.

B. Messaging & Engagement

Welcome Message - Message shown when a user opens the chatbox.
No Match Message - Fallback response when no answer is found.
Fuzzy Match - Matches similar keywords/questions even if not exact.
Fuzzy Threshold - Controls strictness of fuzzy matching.
Lead Capture - Collects visitor name/email before or during chat.
Lead Capture Prompt - Message shown when asking for user details.

C. Widget Appearance

Widget Position - Places launcher on left or right side.
Widget Size - Controls launcher diameter/visual footprint.
Brand/Theme Colors - Matches widget with your site branding.
Avatar Size - Controls bot avatar size inside chat UI.
Animation - Adds attention effects like pulse/shake/float.
Chatbox Width/Height - Controls conversation panel dimensions.

D. System & Performance

Items Per Page - Pagination size for admin tables.
Log Retention Days - Days to keep logs before cleanup.
Auto Cleanup - Automatically deletes old data by retention rule.
Enforce HTTPS - Blocks insecure non-HTTPS requests (non-localhost).
Enforce Admin CSRF - Requires CSRF token for admin write operations.

E. Categories

Add Category - Creates new grouping for FAQ/chat flows.
Recommended Categories - Up to 3 categories shown first in widget.
Delete Category - Removes unused category (or merge/reassign logic applies).

F. Embed Code

API Base URL - Defines backend URL used by widget script.
Allowed Widget Domains - Restricts where widget can run.
Widget Domain Policy - restricted enforces allowed domain list.
Regenerate / Copy Code - Refreshes and copies embed script.

2.4 Pro Features in Settings (Pro)

A. Human Handoff (Pro)

Enable Handoff - Activates escalation to human support.
Escalate After Unmatched - Number of failed matches before handoff.
Handoff Message - Message shown when escalation triggers.
Support URL - Link users click to contact human support.
Business Hours - Optional time window to trigger handoff behavior.

B. AI Powered Responses (Pro)

AI Provider - Selects backend LLM service.
API Key - Auth key for selected provider.
Load Models - Fetches available models for that provider/key.
AI Model - Model used for response generation.
Test Connection - Validates key/model/provider setup.
Max Tokens - Maximum response output length from AI model.
System Instructions - Defines bot behavior/tone/rules.
AI Disclaimer - Optional caution text shown under AI answers.

C. Vector Retrieval (RAG) (Pro)

Enable RAG - Allows retrieval from indexed website content.
Use PostgreSQL pgvector - Enables scalable vector storage/search.
Embedding Provider - Service used to convert text to vectors.
Embedding API Key - Authentication for embedding provider.
Fetch Models - Loads available embedding models.
Embedding Model - Model used for indexing and query embeddings.
Test Embedding Connection - Verifies embedding endpoint works.
Crawl Root URL / Sitemap - Defines crawl starting points.
Max Pages / Max Depth - Controls crawl size and recursion depth.
Chunk Size / Overlap - Controls text segmentation for retrieval quality.
Include / Exclude Patterns - Fine control over crawled URLs.
Resume Mode - Skips already indexed URLs during recrawl.
Crawl Website Content - Starts indexing job.
RAG Ranking Mode - Controls ranking strategy (Balanced / Exact Product First).

2.5 FAQs Page

Add FAQ - Manual Q&A creation with unique keyword.
Edit/Delete FAQ - Maintain and correct existing responses.
Import File - Bulk upload FAQs from TXT/CSV/CSB/DOCX.
Delimiter Option - Parses custom file formats (:, ,, |, etc).
Duplicate Keyword Handling - Skip or suffix duplicates during import.
Category Handling - Create missing categories or use fallback category.
Import Summary - Shows added/rejected/duplicate counts.

2.6 Logs Page

Session Filters - Search by session key, name, or email.
Show Chat - Opens chat history for selected session only.
Leads Table - Displays captured visitor contact details.
Pagination - Navigate large datasets efficiently from top/bottom controls.

2.7 Frontend Behavior

Widget Open - User opens launcher and enters chat.
Welcome/Categories - Intro and recommendations appear (if enabled).
User Query Handling:
- Free: FAQ + fuzzy match flow.
- Pro: FAQ + AI + RAG + handoff rules.
Lead Collection - Name/email prompt appears when enabled.
Logging - Session/messages/leads saved for analytics.

2.8 Troubleshooting

Widget not visible - Validate embed code, domain policy, and browser console.
Short AI answers - Try another model/provider, raise max tokens, test provider response metadata.
RAG not answering - Confirm crawl success, embedding config, and ranking mode.
Install blocked - Verify install token and lock/maintenance behavior.

2.9 Recommended Rollout Path

Start with FAQ + categories - Build reliable baseline answers.
Enable fuzzy match - Improve question tolerance.
Enable lead capture - Start collecting qualified contacts.
(Pro) Enable AI - Handle broader natural-language queries.
(Pro) Enable RAG - Ground answers in your own site content.
(Pro) Enable handoff - Escalate complex user needs to humans.
Finalize security + deploy - Lock policy and go production.