# https://github.com/trypromptly/LLMStack Project Manual Generated at: 2026-06-18 19:55:10 UTC ## Table of Contents - [Overview and System Architecture](#page-1) - [Core Features: Apps, Agents, and Sheets](#page-2) - [AI Integrations and Data Processing](#page-3) - [Deployment, Operations, and Troubleshooting](#page-4) ## Overview and System Architecture ### Related Pages Related topics: [Core Features: Apps, Agents, and Sheets](#page-2), [Deployment, Operations, and Troubleshooting](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) - [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json) - [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py) - [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py) - [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py) - [web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json) - [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js) - [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js)
# Overview and System Architecture ## 1. Project Purpose and Scope LLMStack is an open-source, no-code platform for building generative AI agents, workflows, applications, and chatbots that connect to user data and business processes. The project tagline describes it as an "Open-source platform to build AI Agents, workflows and applications with your data" — see the documentation landing at [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js). The repository is organized into three primary top-level directories that map directly onto the runtime architecture: | Directory | Role | Source | |---|---|---| | `llmstack/` | Python/Django backend, CLI, Docker orchestration | [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) | | `llmstack/client/` | React + CRACO no-code builder UI | [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json) | | `web/` | Docusaurus documentation site | [web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md) | The platform supports multi-tenancy (organizations, granular permissions, viewer/collaborator roles), model chaining across providers (OpenAI, Cohere, Stability AI, Hugging Face, and others — see [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js)), and can be deployed either as a hosted cloud offering (Promptly) or self-hosted on-premise. See [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) for the official feature list, which includes Agents, multi-model chaining, data import (CSV, TXT, PDF, DOCX, PPTX), Slack/Discord triggers, and HTTP API access. ## 2. High-Level Runtime Architecture A single `llmstack` command-line invocation bootstraps the entire stack. It pulls and starts a Docker Compose topology that includes the API service, an RQ worker, Postgres, Redis, and Weaviate. The architecture is illustrated below. ```mermaid flowchart LR User[User / Browser] -->|HTTP| FE[React No-Code Builder
llmstack/client] FE -->|REST/WS| API[Django + DRF API
llmstack/server] API --> ORM[(Postgres
metadata, orgs, apps)] API --> VDB[(Weaviate
vector store)] API --> Cache[(Redis
cache + RQ broker)] API --> RQ[RQ Worker
async jobs] RQ --> VDB API --> Providers[(External Providers
OpenAI, Cohere, Stability, HF,
Apollo, HeyGen, Mistral, Meta,
Pinecone, Qdrant, Singlestore, Weaviate)] Docs[Docusaurus Site
web/] -.->|Static docs| User ``` Key responsibilities of each tier: - **Frontend (`llmstack/client`)** — A Create React App / CRACO application built on React 18, Recoil state, React Router, Lexical editor, `react-ace`, `react-markdown`, `react-dropzone`, and `styled-components`. Source: [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json). - **Backend (`llmstack/server`)** — A Django 4.2 project exposed via WSGI ([llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py)) with `ALLOWED_HOSTS`, storage backends, and provider registries configured in [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py). - **Vector store** — Weaviate is the default vector database; a `dumpvectordata` management command at [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py) reads `WEAVIATE_URL` from Django settings and uses the `weaviate` Python client to introspect schemas and objects for backup/migration. - **Async jobs** — An RQ worker process consumes queued tasks using Redis as the broker. - **Providers** — Backend modules registered as a slug-keyed list in settings (`linkedin`, `apollo`, `heygen`, `mistral`, `meta`, `pinecone`, `qdrant`, `singlestore`, `weaviate`, …). Each entry includes a `processor_packages` namespace and an optional Pydantic `config_schema`. Source: [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py). ## 3. Static Assets, Storage, and Documentation Layer The backend separates user assets, generated files, and static frontend bundles onto different filesystems via Django `STORAGES`. The defaults — `assets`, `public_assets`, `generatedfiles`, and `staticfiles` — are all configurable through environment variables (`ASSETS_ROOT`, `PUBLIC_ASSETS_ROOT`, `GENERATEDFILES_ROOT`, `STATIC_URL`) as declared in [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py). The React build output lives at `/build/static` and is served by Django in production. The `web/` directory is a separate Docusaurus 3 site (Node ≥ 18, see [web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json)). It hosts user-facing documentation and embeds the GitHub repo hero video and feature carousel; the homepage hero is defined in [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js), and the three feature cards (Model Chaining, Bring your own Data, Build Apps Collaboratively) are defined in [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js). ## 4. Deployment, Release Cadence, and Known Operational Issues The product follows an iterative 0.2.x release line. Recent milestones include Sheets and the AI sheet builder (v0.2.5), Voice agents with OpenAI realtime API and Twilio voice integration (v0.2.6), and token-usage info plus message feedback (v0.2.4). See the release history links in the community context for full changelogs. Fresh-installation issues reported by the community map directly to subsystems described above: - **Postgres authentication / migrations** — `FATAL: password authentication failed for user "llmstack"` (issue #286) and `LLMStack api service fails to start` due to a v2 Pydantic migration error in `migration.py` (issue #288) point to misconfigured `DATABASES` credentials in [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py) and to migration scripts that must be regenerated against Postgres 16. - **Docker daemon not reachable** (issue #298) — The CLI shells out to `docker compose`, which requires a running Docker socket; on Windows this is compounded by a `NamedTemporaryFile` lock preventing `docker compose --env-file` from reading the env (issue #299). - **`DisallowedHost` / `ALLOWED_HOSTS`** (issue #291) — A self-hosted install behind a custom hostname must add the host to `ALLOWED_HOSTS` in [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py). - **Dev-environment image pull errors** (issue #295) — `docker-compose.dev.yml` references the locally built `llmstack-app` image; the image must be built locally before `up`. - **File-chat app bug** (issue #304) — `psycopg2.errors.UndefinedColumn: column "config..."` indicates an app-model migration drift between client schema and the Postgres tables created by [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py). - **Enterprise governance** (issue #308) — A requested feature for built-in audit trails and policy enforcement middleware for no-code agents; this is a roadmap item, not yet implemented in source. ## See Also - [llmstack/client/README.md](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/README.md) — React client scripts and build pipeline - [web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md) — Building and deploying the Docusaurus docs site - [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py) — Weaviate vector-data backup utility - Official docs: - Development guide: --- ## Core Features: Apps, Agents, and Sheets ### Related Pages Related topics: [Overview and System Architecture](#page-1), [AI Integrations and Data Processing](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) - [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json) - [llmstack/client/README.md](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/README.md) - [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py) - [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py) - [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py) - [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js) - [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js) - [web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json)
# Core Features: Apps, Agents, and Sheets LLMStack is positioned as a no-code platform for building generative AI agents, workflows, applications, and chatbots by chaining multiple large language models and connecting them to user data. Source: [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md). The product's headline building blocks are **Apps**, **Agents**, and (newer in the 0.2.x line) **Sheets**, each implemented as a first-class object that can be built visually and exposed via HTTP API, Slack, or Discord. ## 1. Platform Overview The repository ships two distinct front-ends that share the same Django backend: | Surface | Tech | Role | Source | | --- | --- | --- | --- | | Marketing site | Docusaurus 2 (React) | Documentation, feature marketing, video embed | [web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json), [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js) | | App builder UI | Create React App (CRACO, Recoil, Lexical editor) | Visual no-code editor for apps/agents | [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json) | | API | Django 4.2 (WSGI) | Serves builder, REST endpoints, storage backends | [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py) | The static React build is consumed by Django directly. Source: [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py) defines `REACT_APP_DIR = os.path.join(BASE_DIR, "client")` and `STATICFILES_DIRS = [os.path.join(REACT_APP_DIR, "build", "static")]`, meaning the CRA bundle is dropped into Django's static pipeline rather than being deployed as a separate service. The same settings file also declares four `STORAGES` backends — `default`, `staticfiles`, `generatedfiles`, and `assets`/`public_assets` — supporting file uploads, AI-generated outputs, and shared brand assets. The marketing page describes the platform in three feature cards — "Model Chaining", "Bring your own Data", and "Build Apps Collaboratively" — confirming that chaining LLMs, ingesting external data, and multi-user collaboration are first-class concerns. Source: [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js). ## 2. Apps In LLMStack terminology, an **App** is a runnable chain of one or more model calls plus optional data sources. The README enumerates several built-in categories: AI SDRs (Sales Development Representatives), Research Analysts, RPA automations, text generation, chatbots, multimedia generation, conversational AI, and search augmentation. Source: [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md). Apps are not hand-coded by users; they are assembled in the browser-based builder that ships as a CRA app. Source: [llmstack/client/README.md](https://github.com/trypromptly/LLMStack/blob/main/llmstack client/README.md) confirms the app is bootstrapped with Create React App, and [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack client/package.json) shows it uses `lexical` (rich-text editing), `react-ace` (code-style config editing), `react-dropzone` (file uploads), and `notistack` (notifications) — a stack consistent with a node-graph editor on top of a chat/preview surface. Apps can be exposed over HTTP, triggered from Slack or Discord, and shared publicly or with view/edit roles. Source: [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) ("Apps or chatbots built with LLMStack can be accessed via HTTP API. You can also trigger your AI chains from Slack or Discord") and [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js) (granular permission model with viewer and collaborator roles). ```mermaid flowchart LR User[Builder UI
React + Recoil] -->|Saves chain config| API[Django API
WSGI] API -->|Persists app| DB[(Postgres)] API -->|Indexes vectors| W[(Weaviate)] API -->|Queues jobs| R[(Redis)] User -->|Runs app| API API -->|Streams output| User API -->|Webhook| Slack[Slack/Discord] ``` A known issue from the community — file chat template failing to create an app with `psycopg2.errors.UndefinedColumn: column "config` — highlights that the app-config column is part of the persistent schema and that migrations must be applied before templates can be instantiated. Source: community context referencing [issue #304](https://github.com/trypromptly/LLMStack/issues/304). ## 3. Agents Agents are a specialised class of app that can call tools, browse the web, and iterate. Source: [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) describes "AI SDRs", "Research Analysts", and "RPA Automations" as the canonical agent types, all built "without writing any code" by chaining models and connecting internal or external tools. The provider registry inside the server enumerates the integrations an agent can use at runtime. Source: [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack server/settings.py) declares providers including `linkedin` (with `llmstack.processors.providers.linkedin`), `apollo` (with `ApolloProviderConfig`), `heygen`, `mistral` (with `MistralProviderConfig`), `meta` (with `MetaProviderConfig`), plus vector-store options `pinecone`, `qdrant`, `singlestore`, and `weaviate`. Each entry carries a `slug`, a `processor_packages` list of import paths, and optionally a Pydantic `config_schema` — the same shape used by the agent runtime to discover and instantiate tools. Release 0.2.6 added voice agents built on the OpenAI realtime API plus a Twilio voice integration, which are agent types that stream audio instead of text. Source: community context referencing [release v0.2.6](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.6). A frequent community request is for a governance and compliance layer on top of no-code agents — automatic audit trails and policy enforcement middleware for the tool calls a non-technical builder wires up. Source: community context referencing [issue #308](https://github.com/trypromptly/LLMStack/issues/308). This is currently a feature request rather than shipped behaviour. ## 4. Sheets **Sheets** is the most recent addition. They first appeared in release 0.2.4 alongside token-usage info in history and message feedback, were expanded with an AI sheet builder in 0.2.5, and continued to receive bug fixes in subsequent releases. Source: community context referencing [v0.2.4](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.4) and [v0.2.5](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.5). A Sheet treats the chain-of-LLMs abstraction as a row-by-row data pipeline: each row is fed through the same configured chain and the outputs are written back into a tabular view, analogous to a spreadsheet formula that happens to be a generative AI call. The frontend dep `react-papaparse` in [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack client/package.json) supports CSV import/export for that tabular surface, and `liquidjs` is used to template per-row prompts — a pattern consistent with sheet-style row processing. Token-usage info in history (v0.2.4) and the AI sheet builder (v0.2.5) tie Sheets into the same observability and authoring surfaces as chat-style Apps, so an operator can inspect the cost of a generated column after a run completes. ## 5. Operational Notes from the Community Several common issues stem from the local-first deployment story: - **Fresh install on macOS / Conda** — `llmstack doesn't start on a fresh install` (v0.2.6, M3 Max). Source: [issue #297](https://github.com/trypromptly/LLMStack/issues/297). - **Docker daemon not running** — startup aborts when the CLI cannot reach the Docker socket. Source: [issue #298](https://github.com/trypromptly/LLMStack/issues/298). - **Windows NamedTemporaryFile lock** — the CLI fails to start containers because the temp file passed to `docker compose --env-file` is held open. Source: [issue #299](https://github.com/trypromptly/LLMStack/issues/299). - **Migration on fresh install** — `migration.py` misconfiguration against Postgres 16. Source: [issue #288](https://github.com/trypromptly/LLMStack/issues/288). - **Dev compose pull access denied** for `llmstack-app` and `llmstack-runner` images. Source: [issue #295](https://github.com/trypromptly/LLMStack/issues/295). - **Postgres password authentication failure** for the `llmstack` user. Source: [issue #286](https://github.com/trypromptly/LLMStack/issues/286). - **Disallowed Host / ALLOWED_HOSTS** after fresh pipx install. Source: [issue #291](https://github.com/trypromptly/LLMStack/issues/291). These are all first-startup, environment-level problems and unrelated to the app/agent/sheet authoring surface itself, but they are the dominant support load in the issue tracker and worth flagging for any new operator. ## See Also - [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) — high-level product overview and feature list. - [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py) — provider registry, storage backends, and static-asset wiring. - [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py) — operator command for exporting Weaviate vector data, relevant when migrating Sheets/apps that index into the bundled vector store. - Release notes: [v0.2.4](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.4), [v0.2.5](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.5), [v0.2.6](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.6). --- ## AI Integrations and Data Processing ### Related Pages Related topics: [Core Features: Apps, Agents, and Sheets](#page-2), [Deployment, Operations, and Troubleshooting](#page-4)
Related Source Files The following source files were used to generate this page: - [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py) - [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py) - [llmstack/server/consumers.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/consumers.py) - [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) - [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json) - [web/src/components/HomepageFeatures/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/components/HomepageFeatures/index.js) - [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js)
# AI Integrations and Data Processing LLMStack is a no-code platform for building generative AI agents, applications, and chatbots. The "AI Integrations and Data Processing" layer is the subsystem that wires third-party model and vector store providers into LLMStack, ingests user data, vectorizes it, and streams results back to client applications in real time. This page documents the components, configuration model, and runtime flow of that subsystem based on the source code in the repository. ## Provider Integration Framework LLMStack exposes a registry of providers that is declared centrally in Django settings. Each provider entry contains a display `name`, one or more `processor_packages` to import, a stable `slug` used in URLs and API calls, and an optional `config_schema` pointing at a Pydantic class that defines the provider's settings UI and validation rules. Source: [llmstack/server/settings.py]() The registered providers visible in `settings.py` include: | Category | Providers | | --- | --- | | Large Language Models | OpenAI, Cohere, Anthropic, Google, Mistral, Meta | | Vector Databases | Weaviate, Pinecone, Qdrant, Singlestore | | Data Enrichment | LinkedIn, Apollo | | Media Generation | HeyGen, Stability AI | Because providers are registered by `slug`, additional providers can be added by extending the same list without touching the application code that consumes them. The `processor_packages` field maps the slug to a Python package path that is dynamically imported when a user instantiates that provider inside the no-code builder. ## Data Ingestion and Vectorization LLMStack's data layer accepts heterogeneous user content and converts it into vector embeddings stored in a vector database. The README documents the supported input formats and source connectors: Source: [README.md]() - **File formats**: CSV, TXT, PDF, DOCX, PPTX, and images. - **Connectors**: direct upload, Google Drive, Notion, websites, and sitemaps. The platform handles preprocessing and vectorization automatically and writes the resulting embeddings into the bundled vector database. The management command `dumpvectordata.py` exposes the vector store schema for backup or migration. It calls Weaviate's REST endpoint at `${WEAVIATE_URL}/v1/schema` to fetch the class definitions and iterates the objects in each class. Source: [llmstack/base/management/commands/dumpvectordata.py]() The command defines Pydantic models (`WeaviateClassObject`, `WeaviateClass`, `WeaviateSchema`) that mirror Weaviate's REST schema response, including `vectorWeights`, `vectorIndexType`, `creationTimeUnix`, and `properties`. This makes the dump output machine-readable and validates structure before serialization. The storage layer is configured in `settings.py` using Django's `STORAGES` dictionary, with separate backends for static files, generated files, assets, and public assets. Source: [llmstack/server/settings.py]() Asset locations such as `ASSETS_ROOT` and `PUBLIC_ASSETS_ROOT` default to paths under `/home/appuser/data/`, ensuring generated media is persisted outside the container's ephemeral filesystem. ## Real-time App Runner and Streaming User requests reach the model layer through Django Channels WebSocket consumers. The `AppConsumer` class in `consumers.py` accepts a payload, builds an `AppRunnerRequest`, and invokes `PlaygroundViewSet().get_app_runner_async()` to materialize a session-bound runner. Source: [llmstack/server/consumers.py]() The consumer iterates `app_runner.run(app_runner_request)` as an async generator. Two response types are handled: - `OUTPUT_STREAM_CHUNK` — forwarded as raw text to the WebSocket so the client renders partial tokens. - `OUTPUT` — wrapped in a `done` event JSON object that includes the originating `request_id` and accumulated `data.chunks`. A `StoreAppConsumer` subclass extends `AppConsumer` and injects a `_app_slug` from the WebSocket route, allowing apps sourced from the built-in app store to share the same streaming pipeline. Source: [llmstack/server/consumers.py]() The streaming pattern is what enables features such as voice agents over the OpenAI realtime API (introduced in [v0.2.6](https://github.com/trypromptly/LLMStack/releases/tag/v0.2.6)) and Twilio voice integration, where incremental responses must be pushed to the client as they are produced. ## No-Code Builder and Client Surface The integration story is completed by the React-based no-code builder that lives in `llmstack/client/`. The frontend depends on libraries such as `react-ace` for editing, `react-dropzone` for uploads, `lexical` for rich-text input, `pdfjs-dist` for PDF rendering, and `recoil` for state management. Source: [llmstack/client/package.json]() The marketing documentation site at `web/` mirrors the same capabilities. Its `HomepageFeatures` component advertises three pillars: model chaining across OpenAI, Cohere, Stability AI, and Hugging Face; bringing your own data from URLs, sitemaps, PDFs, audio, and presentations; and collaborative app sharing. Source: [web/src/components/HomepageFeatures/index.js]() The landing page (`web/src/pages/index.js`) embeds the official demo video and links directly to both the cloud offering and the self-hosted quickstart. ## Operational Notes and Known Issues Several issues documented by the community affect fresh-install paths that touch this subsystem: - Migrations can fail on a fresh install because the V2 Pydantic migration script does not match the expected column shape in PostgreSQL 16 ([Issue #288](https://github.com/trypromptly/LLMStack/issues/288)). - On Windows, `NamedTemporaryFile` keeps the `--env-file` for `docker compose` open, which prevents Docker from reading it ([Issue #299](https://github.com/trypromptly/LLMStack/issues/299)). - A missing `ALLOWED_HOSTS` entry causes the API to reject browser clients after `docker compose up` ([Issue #291](https://github.com/trypromptly/LLMStack/issues/291)). - PostgreSQL password authentication failures during `llmstack-api-1` boot are typically caused by `POSTGRES_PASSWORD` mismatch between `docker-compose.yml` and the env file ([Issue #286](https://github.com/trypromptly/LLMStack/issues/286)). These operational concerns do not change the AI integration architecture but are the most common failure modes reported when standing up the vector and model stack locally. ## See Also - [LLMStack Introduction](https://docs.trypromptly.com/llmstack/introduction) - [Development Guide](https://docs.trypromptly.com/llmstack/development) - [Contributing Guide](https://docs.trypromptly.com/llmstack/contributing) - [Promptly Cloud Offering](https://trypromptly.com) --- ## Deployment, Operations, and Troubleshooting ### Related Pages Related topics: [Overview and System Architecture](#page-1), [AI Integrations and Data Processing](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) - [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py) - [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py) - [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py) - [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json) - [web/package.json](https://github.com/trypromptly/LLMStack/blob/main/web/package.json) - [web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md) - [web/src/pages/index.js](https://github.com/trypromptly/LLMStack/blob/main/web/src/pages/index.js)
# Deployment, Operations, and Troubleshooting LLMStack is shipped as a Python package (`pip install llmstack`) that bootstraps a Docker-based runtime stack on first launch. The project bundles a Django REST/API backend, a Create-React-App front end, a Docusaurus documentation site, and a set of backing services (PostgreSQL, Redis, Weaviate, an RQ worker, and a code "runner") that are orchestrated via `docker compose`. This page documents how the application is wired for production-style deployment, the operational levers exposed in source, and the failure modes most often reported by users in the community. ## Deployment Architecture The runtime is a Django + React application packaged into a small CLI launcher. The launcher pulls container images, writes an `--env-file`, and waits for the API container to become healthy before opening the browser. ```mermaid flowchart LR User[Operator] -->|llmstack CLI| CLI[Python launcher] CLI -->|docker compose| Compose[docker-compose stack] Compose --> API[Django API + Gunicorn/WSGI] Compose --> RQ[RQ worker] Compose --> Runner[Code runner] Compose --> PG[(PostgreSQL)] Compose --> Redis[(Redis)] Compose --> Weaviate[(Weaviate vector DB)] API --> Static[Static files: STATIC_URL] API --> Assets[ASSETS_ROOT / GENERATEDFILES_ROOT] React[React SPA build] --> API ``` The Django backend exposes a standard WSGI entry point — `application = get_wsgi_application()` is set in [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py) — which makes the API container compatible with any WSGI-compliant server (Gunicorn, uWSGI, mod_wsgi). The settings module declares `DJANGO_SETTINGS_MODULE = "llmstack.server.settings"` as the default, so any container that honors that variable will boot the application correctly. Source: [llmstack/server/wsgi.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/wsgi.py). The front end is a CRA build produced by `npm run build` in [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json), whose output is served as static assets by Django. Django is configured to look for the React bundle at `client/build/static`: ```python REACT_APP_DIR = os.path.join(BASE_DIR, "client") STATICFILES_DIRS = [os.path.join(REACT_APP_DIR, "build", "static")] ``` Source: [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py). ## Configuration Surface LLMStack's settings module is environment-driven. The following knobs are read at boot from environment variables and are the primary levers for an operator tuning a deployment: | Setting | Environment Variable | Purpose | |---|---|---| | `STATIC_URL` | `STATIC_URL` | URL prefix for compiled React/CSS assets | | `GENERATEDFILES_ROOT` / `GENERATEDFILES_URL` | same | Where generated artifacts (e.g. sheet outputs) are written and served from | | `ASSETS_ROOT` / `ASSETS_URL` | same | Per-user uploaded assets (documents, audio, video) | | `PUBLIC_ASSETS_ROOT` / `PUBLIC_ASSETS_URL` | same | Publicly addressable assets | | `WEAVIATE_URL` | `WEAVIATE_URL` | Endpoint for the bundled vector database | These map directly to the `STORAGES` dictionary in settings, which configures distinct `FileSystemStorage` backends for `default`, `staticfiles`, `generatedfiles`, `assets`, and `public_assets`. Source: [llmstack/server/settings.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/server/settings.py). The README highlights that administrators log in at `http://localhost:3000/admin` to manage users and organizations. The same file documents that the platform can be deployed "to the cloud or on-premise", so the static-file and storage paths above are the integration points for mounting persistent volumes. Source: [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md). The bundled documentation site under `web/` is a separate Docusaurus 3 application built with `yarn build` and deployed through `yarn deploy`, per [web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md). It is independent of the application runtime. ## Operational Commands LLMStack ships standard Django management commands. One operator-facing example is `dumpvectordata`, which connects to Weaviate via `WEAVIATE_URL`, fetches the schema, and serializes classes and objects for backup or migration: ```python WEAVIATE_URL = settings.WEAVIATE_URL client = weaviate.Client(WEAVIATE_URL) ``` Source: [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py). Operationally, the most common workflow is the `llmstack` CLI itself, which on first run downloads and starts the docker-compose stack, then polls the API until it answers. After bootstrap, operators can `docker compose exec api python manage.py ` to invoke any Django management command inside the API container. ## Troubleshooting Common Failures Community evidence shows that the majority of reported incidents occur during the first-launch flow rather than in steady-state operation. The recurring failure modes and their remedies are: **1. Docker daemon not reachable.** The CLI requires an active Docker socket. On macOS/Windows this means Docker Desktop must be running; on Linux the user must be in the `docker` group or invoke with `sudo`. Reported in [issue #298](https://github.com/trypromptly/LLMStack/issues/298) ("very buggy") where the user saw `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`. **2. Windows `NamedTemporaryFile` lock.** On Windows, the temp file the CLI passes as `docker compose --env-file` remains locked while open, preventing Docker from reading it. The workaround is to close the file before invoking `docker compose`. Reported in [issue #299](https://github.com/trypromptly/LLMStack/issues/299). **3. PostgreSQL authentication failure.** After containers come up, `llmstack-api` may fail to connect with `password authentication failed for user "llmstack"`. This points to a mismatch between the credentials baked into the compose file and the ones in the `.env`. Operators should regenerate the env file and re-pull images. Reported in [issue #286](https://github.com/trypromptly/LLMStack/issues/286). **4. Django `ALLOWED_HOSTS` rejection.** Fresh installs behind a reverse proxy or non-localhost hostname fail with `Disallowed Host`. Operators must add the public hostname to `ALLOWED_HOSTS` (or set `DEBUG=False` with the appropriate hosts list). Reported in [issue #291](https://github.com/trypromptly/LLMStack/issues/291). **5. Migration failure on first boot.** A misconfigured `migration.py` against PostgreSQL 16 has caused startup failures on fresh installs (Pydantic v2 migration warnings appear in the trace). Operators should ensure the database is at a supported version and rerun migrations. Reported in [issue #288](https://github.com/trypromptly/LLMStack/issues/288). **6. Dev environment compose pull errors.** When using the developer compose file, `pull access denied for llmstack-app` indicates the local image tag is not published; builders should `docker build` from source before `docker compose up`. Reported in [issue #295](https://github.com/trypromptly/LLMStack/issues/295). **7. Schema mismatch in the file chat app.** A migration drift surfaced as `psycopg2.errors.UndefinedColumn: column "config...` when creating a file-chat app from a template; users must run the latest migrations after upgrading. Reported in [issue #304](https://github.com/trypromptly/LLMStack/issues/304). For backup and recovery, the management command at [llmstack/base/management/commands/dumpvectordata.py](https://github.com/trypromptly/LLMStack/blob/main/llmstack/base/management/commands/dumpvectordata.py) is the canonical way to export vector embeddings, while standard PostgreSQL `pg_dump` covers relational state. ## See Also - Project Overview and Features — [README.md](https://github.com/trypromptly/LLMStack/blob/main/README.md) - Frontend build pipeline — [llmstack/client/package.json](https://github.com/trypromptly/LLMStack/blob/main/llmstack/client/package.json) - Documentation site — [web/README.md](https://github.com/trypromptly/LLMStack/blob/main/web/README.md) - Release notes — [GitHub Releases](https://github.com/trypromptly/LLMStack/releases) --- --- ## Pitfall Log Project: trypromptly/LLMStack Summary: Found 15 structured pitfall item(s), including 6 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/304 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/291 ## 3. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/295 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/288 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/286 ## 6. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/297 ## 7. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/299 ## 8. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/308 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/trypromptly/LLMStack/issues/298 ## 10. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/trypromptly/LLMStack ## 11. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/trypromptly/LLMStack ## 12. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/trypromptly/LLMStack ## 13. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/trypromptly/LLMStack ## 14. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/trypromptly/LLMStack ## 15. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/trypromptly/LLMStack