Frequently Asked Questions¶

This page answers the most common questions about iPassion AI Portal. Questions are grouped by topic for easy navigation.

Data & Privacy¶

Is my data being sent to external servers?¶

By default, no. iPassion AI Portal runs entirely within your own infrastructure. Your conversations, uploaded documents, and user data stay on your servers and are never transmitted to Anthropic, the Open WebUI project, or any other third party by the portal itself.

Data does leave your environment only when you explicitly configure an external provider:

Ollama models run locally on your own hardware. No data leaves.
OpenAI-compatible APIs — if you connect an external API (OpenAI, Azure OpenAI, Anthropic Claude via an API gateway, etc.), your messages are sent to that provider according to their privacy policy. This is entirely your choice and configuration.
Web search — if you enable the web search RAG feature, queries are forwarded to the configured search engine.

In summary: the portal is a conduit. What you connect it to determines what data moves where. In a fully local setup with Ollama, nothing leaves your network.

The very first account created on a fresh iPassion AI Portal installation automatically becomes the admin account. This is a deliberate security design: the portal requires at least one authenticated owner before it is usable.

This one-time registration step is not optional because:

Without it, the portal would be fully open with no access controls.
The admin account is the only account with full system access, and that privilege must be intentionally claimed.

After the admin account is created, you can control whether further self-registration is allowed via the ENABLE_SIGNUP environment variable. In most enterprise deployments this is set to false, and the admin creates additional accounts manually or via SSO/LDAP.

Chat & Context¶

I am getting a "Prompt is too long" or "context length exceeded" error. What does this mean?¶

Every language model has a fixed context window — the maximum number of tokens (roughly, word fragments) it can process in a single request. This limit is a property of the model itself, not of iPassion AI Portal.

When your conversation history, system prompt, and any injected RAG context together exceed this limit, the model returns an error.

To resolve this:

Summarize or start a new conversation. Long chat threads accumulate context quickly. Starting fresh is the simplest fix.
Reduce RAG chunk count. If using knowledge base retrieval, lower the RAG_TOP_K setting to inject fewer document chunks per query.
Use a model with a larger context window. Models like llama3.1:70b, mistral-nemo, or any model with a 32K+ context window handle longer conversations.
Enable context trimming filters. The portal supports pipeline filters that automatically trim older messages when the context approaches the limit.
Increase num_ctx for Ollama models. In the model parameters, you can increase the context size up to the model's maximum supported value — but be aware this increases VRAM usage significantly.

My RAG (knowledge base) results are poor or the model ignores the retrieved documents. How do I fix this?¶

Poor RAG performance when using Ollama is most commonly caused by an insufficient context window configured for the model.

By default, many Ollama models run with a context window of only 2048 tokens. When the portal retrieves and injects document chunks, they consume a large portion of this budget, leaving little room for the conversation. The model may appear to ignore the documents or truncate them silently.

The most impactful fix: increase num_ctx to 8192 or higher.

You can do this in the model settings inside iPassion AI Portal:

Navigate to Admin Panel > Models.
Select the model you are using.
Under Advanced Parameters, set num_ctx to 8192 (or higher, up to the model's maximum).
Save and retry your query.

Additional tuning options:

Adjust CHUNK_SIZE and CHUNK_OVERLAP to produce better-sized chunks for your document types.
Enable hybrid search (ENABLE_RAG_HYBRID_SEARCH=true) to combine vector and keyword retrieval.
Use a dedicated reranking model (RAG_RERANKING_MODEL) to improve the quality of retrieved chunks before they reach the LLM.
Verify your embedding model is appropriate for your document language and domain.

Why does iPassion AI Portal send multiple API requests for a single message I send?¶

When you send a message, the portal may issue several API calls beyond the primary chat completion. These additional calls are made by Task Models — lightweight model calls that handle background tasks automatically:

Task	Description
Title generation	Automatically generates a descriptive title for new conversations.
Chat tagging	Assigns topic tags to conversations for search and organization.
Query rephrasing	Rewrites your query for better RAG retrieval results.
Autocomplete suggestions	Generates inline prompt completion suggestions as you type.
Follow-up question suggestions	Proposes related questions after a response.

Each of these tasks uses its own model call, which is why you may observe 3–5 API requests per user message in your logs or API usage dashboard.

To reduce API call volume:

Go to Admin Panel > Settings > Interface.
Disable the specific task features you do not need (title generation, tagging, autocomplete, etc.).
You can also assign a faster, cheaper model specifically for tasks under Admin Panel > Settings > Models > Task Model, so these background calls do not consume your primary model's quota.

Docker & Deployment¶

I cannot connect to a service running on my host machine using `localhost` from inside the Docker container. Why?¶

Inside a Docker container, localhost refers to the container itself, not the host machine. When iPassion AI Portal tries to connect to http://localhost:11434 (Ollama, for example), it looks inside its own network namespace and finds nothing there.

Use host.docker.internal instead of localhost:

# Instead of:
OLLAMA_BASE_URL=http://localhost:11434

# Use:
OLLAMA_BASE_URL=http://host.docker.internal:11434

host.docker.internal is a special DNS name that Docker resolves to the host machine's IP address. It works on:

Docker Desktop for macOS
Docker Desktop for Windows
Docker Engine on Linux (when you pass --add-host=host.docker.internal:host-gateway to docker run, or use the equivalent in docker-compose.yml)

For Docker Compose on Linux, add this to your service definition:

extra_hosts:
  - "host.docker.internal:host-gateway"

My service on the host only listens on `127.0.0.1`. How do I make it accessible to the Docker container?¶

A service bound to 127.0.0.1 (the loopback interface) is only accessible to processes running on the host itself. The Docker container has a different network namespace, so it cannot reach a loopback-only service even via host.docker.internal.

Solution: configure the service to listen on 0.0.0.0 (all interfaces), so it accepts connections from the Docker bridge network.

For example, to start Ollama accessible from Docker:

OLLAMA_HOST=0.0.0.0 ollama serve

After this change, Ollama listens on all interfaces, and the container can reach it via host.docker.internal:11434.

Security note: Binding to 0.0.0.0 exposes the service to all network interfaces on the host. Ensure your firewall rules prevent external access if the service should remain internal.

Does iPassion AI Portal support GPU acceleration in Docker?¶

Yes, GPU passthrough is supported for accelerating local model inference.

Linux (Docker Engine):

Install the NVIDIA Container Toolkit, then add the following to your docker-compose.yml:

services:
  ollama:
    image: ollama/ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Windows (Docker Desktop with WSL2):

NVIDIA GPU support in Docker on Windows is available through WSL2 with the NVIDIA CUDA drivers for WSL installed. Configure the same deploy.resources block as Linux — Docker Desktop handles the passthrough automatically.

macOS:

Docker Desktop for macOS does not support GPU passthrough. For GPU-accelerated inference on Apple Silicon, run Ollama natively on the host (outside Docker) and point the portal at http://host.docker.internal:11434.

Updates & Persistence¶

I pulled a new version of the Docker image but the portal has not updated. What do I do?¶

Simply pulling a new image does not update a running container. Docker keeps the container running from its original image until it is explicitly recreated. The correct update sequence is:

# 1. Pull the latest image
docker pull ghcr.io/open-webui/open-webui:main

# 2. Stop the running container
docker compose down

# 3. Recreate the container from the new image
docker compose up -d

The key step most users miss is removing the old container before starting a new one. docker compose down stops and removes the container (but not the volumes), and docker compose up -d recreates it from the newly pulled image.

Do not use docker compose restart — this restarts the existing container from its original image and does not pick up the new pull.

If I delete the Docker container, will I lose all my chats and settings?¶

No — provided your data directory is mounted as a Docker volume (which is the recommended and default configuration).

iPassion AI Portal stores all persistent data in the path specified by DATA_DIR (default: /app/backend/data inside the container). As long as this path is mapped to a host volume, the data survives container deletion and recreation.

Typical docker-compose.yml volume mapping:

volumes:
  - ipassion-data:/app/backend/data

volumes:
  ipassion-data:

You can delete and recreate the container as many times as needed — your conversations, uploaded documents, user accounts, and settings are preserved in the volume.

If you did not configure a volume, the data lives inside the container's writable layer and is lost when the container is removed. Always verify your volume configuration before deleting a container in production.

Users are being logged out after every restart, or I see an "Error decrypting tokens" message. How do I fix this?¶

This is caused by a missing or changing WEBUI_SECRET_KEY.

The portal uses this key to sign JWT session tokens. If the key is not set, a random key is generated at startup — meaning every restart produces a different key, invalidating all previously issued tokens. If the key changes between restarts, existing tokens cannot be verified, producing the "Error decrypting tokens" error.

Fix: set a stable, persistent WEBUI_SECRET_KEY.

Generate a secure key once:

openssl rand -hex 32

Add it to your docker-compose.yml environment:

environment:
  - WEBUI_SECRET_KEY=your-generated-key-here

Once set, keep this value constant across restarts and deployments. Changing it again will invalidate all active sessions.

This almost always means the data volume was not mounted, or was mounted incorrectly, and the container was storing data in its ephemeral writable layer.

When the container was restarted (or recreated), the ephemeral layer was reset, causing the portal to initialize as if it were a fresh installation — prompting you to create a new admin account and showing no prior data.

Immediate steps:

Check your docker-compose.yml and confirm a volume is mounted at /app/backend/data.
If you recreated the container without a volume, the data from the previous container instance may still be recoverable from the old container's filesystem (if it was not pruned). Run docker ps -a to find stopped containers.
Going forward, always configure a named volume or bind mount before starting the portal.

SSL & HTTPS¶

Speech-to-text and text-to-speech features are not working. Why?¶

Browser-based microphone access and speech synthesis APIs require a secure context (HTTPS). Browsers enforce this as a security policy — microphone and speaker access is blocked on plain HTTP connections, regardless of the application.

If iPassion AI Portal is served over HTTP (even on localhost, in some browsers), the following features will not function:

Speech-to-text (microphone input)
Text-to-speech (audio playback via browser APIs)

To enable these features, serve the portal over HTTPS. See the question below for how to set up HTTPS.

Does iPassion AI Portal have built-in HTTPS/TLS support?¶

No. The portal does not handle TLS termination directly. This is by design: TLS is best managed by a dedicated reverse proxy sitting in front of the application.

Recommended approach: use a reverse proxy with automatic TLS.

Common choices:

Nginx Proxy Manager — web UI for managing Nginx reverse proxy rules and Let's Encrypt certificates.
Traefik — Docker-native reverse proxy with automatic Let's Encrypt certificate management via labels.
Caddy — simple reverse proxy that obtains and renews Let's Encrypt certificates automatically with minimal configuration.
Nginx or Apache — traditional reverse proxies with manual or Certbot-managed certificates.

A minimal Caddy configuration for iPassion AI Portal:

portal.example.com {
    reverse_proxy ipassion-portal:8080
}

Caddy automatically obtains a Let's Encrypt certificate for portal.example.com. No further TLS configuration is needed.

Once HTTPS is in place, set WEBUI_SESSION_COOKIE_SECURE=true and update WEBUI_URL to your HTTPS URL.

Offline & Air-Gapped Deployments¶

Can I use iPassion AI Portal without an internet connection?¶

Yes. iPassion AI Portal is fully capable of operating in offline and air-gapped environments.

To run completely offline:

Use Ollama with locally pulled models. All inference happens on-premise with no outbound network calls.
Disable external providers. Set ENABLE_OPENAI_API=false if you are not using any cloud APIs.
Use local embeddings. Set RAG_EMBEDDING_ENGINE=ollama and pull a local embedding model (e.g., nomic-embed-text).
Disable web search. Ensure RAG_WEB_SEARCH_ENABLED=false.
Pre-pull all Docker images before moving to the air-gapped environment, or mirror them to an internal container registry.

In this configuration, the entire stack — portal frontend, backend, models, and vector database — runs within your network with zero external dependencies.

Scalability¶

Is iPassion AI Portal scalable? Can it handle many concurrent users?¶

Yes. iPassion AI Portal is designed to scale horizontally for enterprise workloads.

How to scale:

Component	Scaling approach
Portal backend	Run multiple replicas behind a load balancer. Requires PostgreSQL (instead of SQLite) and Redis for shared state.
Database	Use a managed PostgreSQL service (AWS RDS, Azure Database for PostgreSQL, Google Cloud SQL) for high availability and read replicas.
File storage	Use S3, GCS, or Azure Blob Storage so all replicas share the same file store.
Session state	Use Redis (`REDIS_URL`) so sessions are shared across all backend replicas.
Model inference	Scale Ollama horizontally using `OLLAMA_BASE_URLS` with multiple Ollama instances, or use a cloud API that handles scaling independently.
Orchestration	Deploy on Kubernetes using the official Helm chart for automated scaling, rolling updates, and resource management.

A production-scale deployment typically looks like:

Load Balancer
     |
  ┌──┴──┐
  │     │
Portal  Portal   (2+ replicas)
  │     │
  └──┬──┘
     |
  PostgreSQL + Redis   (shared state)
     |
  S3 / Blob Storage    (shared files)
     |
  Ollama cluster / Cloud API

This architecture supports hundreds of concurrent users and can be scaled further by adding more portal replicas or model inference nodes.

Why is the frontend bundled into the same Docker image as the backend? Does this limit scalability?¶

The frontend is a compiled static Single-Page Application (SPA) built with SvelteKit. Static files are served directly by the backend as a simple file-serving operation — they require no server-side rendering and consume negligible resources.

This bundling is a deliberate simplification that makes deployment easier (one image, one container) without any meaningful scalability trade-off. The static assets can be cached aggressively by a CDN or reverse proxy in front of the portal, so the backend is effectively never the bottleneck for frontend delivery.

When you scale the portal to multiple replicas, each replica serves the same static files — there is no state or coordination required for frontend delivery. Scaling is governed entirely by the backend's dynamic workload (API calls, database queries, LLM proxying), not by static file serving.