Stella AI Chatbot Installation & User Guide

This guide covers both Free and Pro editions in one place. Where a feature is Pro-only, it is marked (Pro).1. Installation1.1 RequirementsNode.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 PrepareExtract 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 install1.3 Configure EnvironmentCreate .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 Applicationnpm start/install - First-time setup wizard./admin - Admin login and dashboard.1.5 Installer StepsOpen 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 WebsiteOpen 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 ChecklistEnable 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 LoginOpen /admin - Access admin entry page.Sign in - Uses credentials from .env.Navigate menu - Overview, Settings, FAQs, Logs.2.2 Overview PageUsage 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 PageA. Core IdentityChatbot 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 & EngagementWelcome 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 AppearanceWidget 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 & PerformanceItems 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. CategoriesAdd 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 CodeAPI 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 PageAdd 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 PageSession 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 BehaviorWidget 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 TroubleshootingWidget 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 PathStart 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.