Open WebUI Chat Interface
Relevant source files
The following files were used as context for generating this wiki page:
Open WebUI provides the primary browser-based chat interface for the Nyansa self-hosted AI stack. It connects to the local Ollama instance to provide users with a graphical environment for interacting with Large Language Models (LLMs), such as qwen2.5:3b.
The interface acts as a frontend component within the Nyansa Docker network, facilitating communication between the user and the underlying AI services. While it primarily interacts with Ollama for chat inference, the broader Nyansa system enhances this interaction via the memory-api service, which provides Retrieval-Augmented Generation (RAG) capabilities over a mounted Obsidian vault.
Sources: README.md:18-20, README.md:55-78
System Architecture and Connectivity
Open WebUI operates as a service within the nyansa internal Docker network. It listens on port 3000 but is bound to 127.0.0.1 to prevent direct external exposure. External access is managed through Caddy, which acts as a reverse proxy providing HTTPS and authentication.
Component Interaction Flow
The following diagram illustrates how Open WebUI interacts with other components in the Nyansa stack:
The diagram shows the communication path from the user through the edge proxy to the chat interface and its backend dependencies.
Sources: README.md:55-78, README.md:80-85
Security Configuration
Nyansa implements several measures to secure the Open WebUI instance:
- Network Isolation: Open WebUI publishes no ports to the host's public interfaces; it is only reachable via the
nyansainternal network or the Caddy proxy. - Disabled Public Sign-up: The service is configured to disable public registration.
- Admin Bootstrapping: An initial admin account is created using environment variables (
WEBUI_ADMIN_EMAILandWEBUI_ADMIN_PASSWORD) only when no users exist, preventing unauthorized account takeover on first boot. - Session Security: The
WEBUI_SECRET_KEYenvironment variable secures user sessions.
Sources: README.md:88-118, README.md:162-178
Configuration Parameters
Open WebUI behavior and connectivity are defined through environment variables in the .env file.
| Variable | Description | Default / Requirement |
|---|---|---|
WEBUI_SECRET_KEY | Secret used for signing session tokens | Required (32+ chars) |
WEBUI_ADMIN_EMAIL | Email for the initial admin account | Required |
WEBUI_ADMIN_PASSWORD | Password for the initial admin account | Required |
OLLAMA_URL | Internal URL for the Ollama service | http://nyansa-ollama:11434 |
Sources: README.md:162-178, services/memory-api/src/config.ts:6-18
Integration with RAG (memory-api)
Open WebUI can leverage the memory-api service to perform semantic searches across an Obsidian vault. While Open WebUI handles the chat UI, the memory-api handles the logic for parsing, chunking, and retrieving relevant note fragments.
This sequence shows the interaction between the chat interface and the RAG service during a search-augmented query.
Sources: services/memory-api/README.md:58-75, services/memory-api/src/app.ts:114-123
Search Execution
To perform a search, Open WebUI (or an automated agent) calls the /search endpoint of memory-api. The request includes the query string and an optional limit for the number of results.
{
"query": "What did I write about Docker?",
"limit": 3,
"tags": ["infra"]
}
Sources: services/memory-api/README.md:58-65, services/memory-api/test/app.test.ts:106-118
Deployment and Lifecycle
Open WebUI is deployed as part of the nyansa Docker Compose stack. During the build and publish process, the service is validated alongside other components to ensure correct port exposure and configuration.
- Release Building: The
scripts/build-publish.shscript prepares the runtime environment, ensuring thedocker-compose.ymlcorrectly references the service. - Health Monitoring: The system uses
scripts/wait-healthy.shto ensure the interface is fully operational before switching traffic. - Model Availability: Open WebUI depends on the
nyansa-ollama-pull-modelcontainer to download the required LLM models (qwen2.5:3b) before the interface becomes functional for chat.
Sources: scripts/build-publish.sh:17-40, README.md:183-188, README.md:200-216
Summary
The Open WebUI Chat Interface serves as the user-facing entry point for the Nyansa AI ecosystem. By integrating with local Ollama inference and the memory-api RAG service, it allows users to interact privately with their personal knowledge base. Security is enforced through network isolation, Caddy-managed HTTPS, and restricted administrative account creation.