Skip to content

An AI-powered search engine with a generative UI

docs: simplify README, Docker guide, and configuration docs (#795)

Yoshiki Miura80f46945fff1
diff --git a/.env.local.example b/.env.local.example
index f90546e4..109e5aa7 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -4,42 +4,25 @@
# =============================================================================
# REQUIRED CONFIGURATION
-# These settings are essential for the application to function
# =============================================================================
-# -----------------------------------------------------------------------------
-# Database Configuration (Required)
-# -----------------------------------------------------------------------------
-# PostgreSQL connection string (supports Neon, Supabase, or standard PostgreSQL)
-# Format: postgresql://[user]:[password]@[host]/[database]?sslmode=require
-#
-# For local development: Use your local PostgreSQL instance
-# DATABASE_URL=postgresql://user:password@localhost:5432/morphic
-#
-# For Docker: Use the postgres service name from docker-compose.yaml
-# DATABASE_URL=postgresql://morphic:morphic@postgres:5432/morphic
-#
-# For cloud providers (Neon, Supabase, etc.): Add ?sslmode=require
-# DATABASE_URL=postgresql://user:password@host/database?sslmode=require
-DATABASE_URL=[YOUR_DATABASE_URL]
-
# -----------------------------------------------------------------------------
# AI Provider Configuration (At least one required)
# -----------------------------------------------------------------------------
-# IMPORTANT: When using non-OpenAI providers, you must update the model
-# configuration in config/models/*.json to use compatible model IDs for your
-# chosen provider. See docs/CONFIGURATION.md for provider-specific model IDs.
+# Set at least one provider API key. Available models are automatically
+# detected and shown in the model selector UI.
+#
+# For Docker: This is the only section you need to configure.
+# Database and search are handled automatically by Docker Compose.
# Option 1: OpenAI
# Get your API key at: https://platform.openai.com/api-keys
OPENAI_API_KEY=[YOUR_OPENAI_API_KEY]
# Option 2: Anthropic Claude
-# Requires updating config/models/*.json with Anthropic model IDs
# ANTHROPIC_API_KEY=[YOUR_ANTHROPIC_API_KEY]
# Option 3: Google Gemini
-# Requires updating config/models/*.json with Google model IDs
# GOOGLE_GENERATIVE_AI_API_KEY=[YOUR_GOOGLE_GENERATIVE_AI_API_KEY]
# Option 4: Vercel AI Gateway
@@ -49,107 +32,91 @@ OPENAI_API_KEY=[YOUR_OPENAI_API_KEY]
# Option 5: Ollama
# Run local AI models with Ollama
# Requires Ollama to be installed and running: https://ollama.com/
-# Models must support 'tools' capability to work with Morphic
# OLLAMA_BASE_URL=http://localhost:11434
# -----------------------------------------------------------------------------
-# Primary Search Provider Configuration (Required - Choose One)
+# Database Configuration (Required for local development)
+# -----------------------------------------------------------------------------
+# Docker: Automatically configured — no need to set this.
+# Local development: Set your PostgreSQL connection string.
+# Cloud providers (Neon, Supabase, etc.): Add ?sslmode=require
+#
+# DATABASE_URL=postgresql://user:password@localhost:5432/morphic
+DATABASE_URL=[YOUR_DATABASE_URL]
+
+# -----------------------------------------------------------------------------
+# Search Provider Configuration (Required for local development)
# -----------------------------------------------------------------------------
+# Docker: SearXNG is included — no search API key needed.
+# Local development: Set at least one search provider key.
+
# Option 1: Tavily Search (Default)
# Get your API key at: https://app.tavily.com/home
TAVILY_API_KEY=[YOUR_TAVILY_API_KEY]
# Option 2: Exa Neural Search (Alternative to Tavily)
# Get your API key at: https://dashboard.exa.ai/
-# Note: API key should be without quotes
# EXA_API_KEY=your_api_key_without_quotes
# Option 3: Firecrawl (Alternative web scraping and content extraction)
# Get your API key at: https://www.firecrawl.dev/app
# FIRECRAWL_API_KEY=[YOUR_FIRECRAWL_API_KEY]
-# -----------------------------------------------------------------------------
-# Additional Search Provider Configuration
-# -----------------------------------------------------------------------------
-# Brave Search (Optional - used for type="general" searches with video/image support)
+# Brave Search (Optional - video/image support for general searches)
# Get your API key at: https://brave.com/search/api/
-# If not configured, general searches will fall back to the configured optimized search provider
# BRAVE_SEARCH_API_KEY=[YOUR_BRAVE_SEARCH_API_KEY]
# =============================================================================
# OPTIONAL FEATURES
-# Enable additional functionality as needed
# =============================================================================
# -----------------------------------------------------------------------------
-# Authentication Configuration (Optional)
+# Authentication (Optional)
# -----------------------------------------------------------------------------
-# By default, authentication is disabled for personal use (ENABLE_AUTH=false)
-# All users share the same anonymous user ID
-# ⚠️ For personal, single-user environments only
-
-# Default: Authentication disabled (anonymous mode)
+# Default: Disabled for personal use. All users share one anonymous user ID.
+# For personal, single-user environments only.
ENABLE_AUTH=false
ANONYMOUS_USER_ID=anonymous-user
-# To enable Supabase authentication, set ENABLE_AUTH=true and configure:
+# To enable Supabase authentication for multi-user deployments:
# Get your project URL and anon key from: https://supabase.com/dashboard
# ENABLE_AUTH=true
# NEXT_PUBLIC_SUPABASE_URL=[YOUR_SUPABASE_PROJECT_URL]
# NEXT_PUBLIC_SUPABASE_ANON_KEY=[YOUR_SUPABASE_ANON_KEY]
-# =============================================================================
-
-# -----------------------------------------------------------------------------
-# Cloud Deployment Configuration
-# -----------------------------------------------------------------------------
-# Enable rate limiting and analytics for cloud deployments
-# When enabled:
-# - Quality mode chat requests are limited to 5 per day
-# - Analytics events are tracked to Vercel Analytics (search mode, model type,
-# conversation turns, etc.)
-# Requires UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN for rate limiting
-# MORPHIC_CLOUD_DEPLOYMENT=true
# -----------------------------------------------------------------------------
-# File Upload Support (Cloudflare R2 / S3-Compatible)
-# Enable file and image upload functionality
+# File Upload (Cloudflare R2 / S3-Compatible)
# -----------------------------------------------------------------------------
-# If not configured, file upload is disabled and /api/upload returns 400.
+# If not configured, file upload is disabled.
# R2_ACCOUNT_ID=[YOUR_R2_ACCOUNT_ID]
-# S3_ENDPOINT=[YOUR_S3_ENDPOINT] # Optional: generic S3-compatible endpoint
+# S3_ENDPOINT=[YOUR_S3_ENDPOINT]
# R2_ACCESS_KEY_ID=[YOUR_R2_ACCESS_KEY_ID]
# R2_SECRET_ACCESS_KEY=[YOUR_R2_SECRET_ACCESS_KEY]
-# R2_BUCKET_NAME=user-uploads # Default: user-uploads
-# R2_PUBLIC_URL=[YOUR_R2_PUBLIC_URL] # Publicly reachable base URL (e.g., https://pub-xxx.r2.dev)
+# R2_BUCKET_NAME=user-uploads
+# R2_PUBLIC_URL=[YOUR_R2_PUBLIC_URL]
# -----------------------------------------------------------------------------
-# Alternative Search Providers
-# Configure different search backends
+# Search Configuration
# -----------------------------------------------------------------------------
# Select search provider (default: tavily)
# SEARCH_API=tavily # Options: tavily, searxng, exa, firecrawl
# SearXNG (Self-hosted)
-# SEARXNG_API_URL=http://localhost:8080 # Or docker: http://searxng:8080
-# SEARXNG_SECRET=[YOUR_SECRET_KEY] # Generate: openssl rand -base64 32
+# SEARXNG_API_URL=http://localhost:8080
+# SEARXNG_SECRET=[YOUR_SECRET_KEY]
# SEARXNG_PORT=8080
# SEARXNG_BIND_ADDRESS=0.0.0.0
# SEARXNG_IMAGE_PROXY=true
# SEARXNG_LIMITER=false
-# SEARXNG_DEFAULT_DEPTH=basic # Options: basic, advanced
+# SEARXNG_DEFAULT_DEPTH=basic
# SEARXNG_MAX_RESULTS=50
# SEARXNG_ENGINES=google,bing,duckduckgo,wikipedia
-# SEARXNG_TIME_RANGE=None # Options: day, week, month, year, None
-# SEARXNG_SAFESEARCH=0 # 0=off, 1=moderate, 2=strict
+# SEARXNG_TIME_RANGE=None
+# SEARXNG_SAFESEARCH=0
-# -----------------------------------------------------------------------------
# Content Extraction
-# -----------------------------------------------------------------------------
-# Default: Tavily Extract API (uses TAVILY_API_KEY configured above)
-#
-# Alternative: Jina AI - Enhanced content extraction from web pages
-# Provides alternative extraction method with different capabilities
-# Get your API key at: https://jina.ai/
+# Default: Tavily Extract API
+# Alternative: Jina AI - Get your API key at: https://jina.ai/
# JINA_API_KEY=[YOUR_JINA_API_KEY]
# -----------------------------------------------------------------------------
@@ -159,35 +126,36 @@ ANONYMOUS_USER_ID=anonymous-user
# ENABLE_LANGFUSE_TRACING=true
# LANGFUSE_SECRET_KEY=[YOUR_LANGFUSE_SECRET_KEY]
# LANGFUSE_PUBLIC_KEY=[YOUR_LANGFUSE_PUBLIC_KEY]
-# LANGFUSE_BASEURL=https://cloud.langfuse.com # Or self-hosted URL
+# LANGFUSE_BASEURL=https://cloud.langfuse.com
# Performance Logging
# ENABLE_PERF_LOGGING=true
# -----------------------------------------------------------------------------
-# Docker Configuration (Optional)
+# Docker Configuration
# -----------------------------------------------------------------------------
-# PostgreSQL credentials for Docker Compose
-# These are only used when running with docker-compose.yaml
-# POSTGRES_USER=morphic # Default: morphic
-# POSTGRES_PASSWORD=morphic # Default: morphic
-# POSTGRES_DB=morphic # Default: morphic
-# POSTGRES_PORT=5432 # Default: 5432
+# PostgreSQL credentials (only for Docker Compose)
+# POSTGRES_USER=morphic
+# POSTGRES_PASSWORD=morphic
+# POSTGRES_DB=morphic
+# POSTGRES_PORT=5432
-# Redis Configuration (Optional)
-# Local Redis is used by default for SearXNG advanced search caching
-# Only set this if you need a custom Redis URL
-# Default: redis://localhost:6379 (automatically used in Docker)
+# Redis (custom URL, default: redis://localhost:6379)
# LOCAL_REDIS_URL=redis://localhost:6379
-# Database SSL Configuration (Optional)
-# Set to true to disable SSL certificate verification
-# Automatically set to true in docker-compose.yaml for local PostgreSQL
-# IMPORTANT: Do NOT set this for cloud databases (Neon, Supabase, etc.)
+# Database SSL (set true for local PostgreSQL without SSL)
+# Do NOT set for cloud databases (Neon, Supabase, etc.)
# DATABASE_SSL_DISABLED=true
# -----------------------------------------------------------------------------
-# Advanced Configuration
+# Cloud Deployment
+# -----------------------------------------------------------------------------
+# Enable rate limiting and analytics for cloud deployments
+# Requires UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN
+# MORPHIC_CLOUD_DEPLOYMENT=true
+
+# -----------------------------------------------------------------------------
+# Advanced
# -----------------------------------------------------------------------------
# Feedback Notifications (Slack)
# SLACK_WEBHOOK_URL=[YOUR_SLACK_WEBHOOK_URL]
diff --git a/README.md b/README.md
index e22d4533..1039c923 100644
--- a/README.md
+++ b/README.md
@@ -19,170 +19,102 @@ An AI-powered search engine with a generative UI.
</div>
-## 🗂️ Overview
-
-- 🛠 [Features](#-features)
-- 🧱 [Stack](#-stack)
-- 🚀 [Quickstart](#-quickstart)
-- 🌐 [Deploy](#-deploy)
-- 👥 [Contributing](#-contributing)
-- 📄 [License](#-license)
-
-📝 Explore AI-generated documentation on [DeepWiki](https://deepwiki.com/miurla/morphic)
-
-## 🛠 Features
-
-### Core Features
+## Features
- AI-powered search with GenerativeUI
-- Natural language question understanding
-- Multiple search providers support (Tavily, Brave, SearXNG, Exa)
- Search modes: Quick and Adaptive
-- Model type selection: Speed vs Quality
-- Inspector panel for tool execution and AI processing details
-
-### Authentication
-
-- User authentication powered by [Supabase Auth](https://supabase.com/docs/guides/auth)
-
-### Guest Mode
-
-- Allow users to try the app without creating an account
-- No chat history stored for guests (ephemeral sessions)
-- Optional daily rate limit per IP address
-- Enable with `ENABLE_GUEST_CHAT=true`
-
-### Chat & History
-
-- Chat history automatically stored in PostgreSQL database
+- Model selector with dynamic provider detection (OpenAI, Anthropic, Google, Ollama, Vercel AI Gateway)
+- Multiple search providers (Tavily, SearXNG, Brave, Exa)
+- Chat history stored in PostgreSQL
- Share search results with unique URLs
-- Message feedback system
- File upload support
-
-### AI Providers
-
-- OpenAI (Default)
-- Anthropic Claude
-- Google Gemini
-- Vercel AI Gateway
-- Ollama
-
-Models are configured in `config/models/*.json` with profile-based settings. When using non-OpenAI providers, update the model configuration files with compatible model IDs. See [Configuration Guide](docs/CONFIGURATION.md) for details.
-
-### Search Capabilities
-
-- URL-specific search
-- Content extraction with Tavily or Jina
-- Citation tracking and display
-- Self-hosted search with SearXNG support
-
-### Additional Features
-
+- User authentication with Supabase Auth
+- Guest mode for anonymous usage
- Docker deployment ready
-- Browser search engine integration
-- LLM observability with Langfuse (optional)
-- Todo tracking for complex tasks
-## 🧱 Stack
+## Installation
-### Core Framework
+### Docker (Recommended)
-- [Next.js](https://nextjs.org/) - React framework with App Router
-- [TypeScript](https://www.typescriptlang.org/) - Type-safe development
-- [Vercel AI SDK](https://ai-sdk.dev) - TypeScript toolkit for building AI-powered applications
+The quickest way to run Morphic locally:
-### Authentication & Authorization
+```bash
+docker pull ghcr.io/miurla/morphic:latest
+```
-- [Supabase](https://supabase.com/) - User authentication and backend services
+Then set up with Docker Compose:
-### AI & Search
+1. Clone the repository and configure environment:
-- [OpenAI](https://openai.com/) - Default AI provider (Optional: Google AI, Anthropic)
-- [Tavily AI](https://tavily.com/) - AI-optimized search with context
-- [Brave Search](https://brave.com/search/api/) - Traditional web search results
-- Tavily alternatives:
- - [SearXNG](https://docs.searxng.org/) - Self-hosted search
- - [Exa](https://exa.ai/) - Meaning-based search powered by embeddings
- - [Firecrawl](https://firecrawl.dev/) - Web, news, and image search with crawling, scraping, LLM-ready extraction, and [open source](https://github.com/firecrawl/firecrawl).
+```bash
+git clone https://github.com/miurla/morphic.git
+cd morphic
+cp .env.local.example .env.local
+```
-### Data Storage
+2. Edit `.env.local` and set at least one AI provider API key:
-- [PostgreSQL](https://www.postgresql.org/) - Primary database (supports Neon, Supabase, or standard PostgreSQL)
-- [Drizzle ORM](https://orm.drizzle.team/) - Type-safe database ORM
-- [Cloudflare R2](https://developers.cloudflare.com/r2/) - File storage (optional)
+```bash
+OPENAI_API_KEY=your_openai_key
+```
-### UI & Styling
+Other supported providers: Anthropic (`ANTHROPIC_API_KEY`), Google (`GOOGLE_GENERATIVE_AI_API_KEY`), Ollama (`OLLAMA_BASE_URL`), [Vercel AI Gateway](https://sdk.vercel.ai/docs/ai-sdk-core/settings#model) (`AI_GATEWAY_API_KEY` — access 200+ models through a single API). See [CONFIGURATION.md](./docs/CONFIGURATION.md) for details.
-- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
-- [shadcn/ui](https://ui.shadcn.com/) - Re-usable components
-- [Radix UI](https://www.radix-ui.com/) - Unstyled, accessible components
-- [Lucide Icons](https://lucide.dev/) - Beautiful & consistent icons
+3. Start all services:
-## 🚀 Quickstart
+```bash
+docker compose up -d
+```
-### 1. Fork and Clone repo
+4. Visit http://localhost:3000 and select your model from the model selector.
-Fork the repo to your Github account, then run the following command to clone the repo:
+Docker Compose starts PostgreSQL, Redis, SearXNG, and Morphic automatically. No additional search API key is needed — SearXNG is included.
-```bash
-git clone [email protected]:[YOUR_GITHUB_ACCOUNT]/morphic.git
-```
+See the [Docker Guide](./docs/DOCKER.md) for more options including building from source and file upload configuration.
-### 2. Install dependencies
+### Local Development
+
+1. Clone and install:
```bash
+git clone https://github.com/miurla/morphic.git
cd morphic
bun install
```
-### 3. Configure environment variables
+2. Configure environment:
```bash
cp .env.local.example .env.local
```
-Fill in the required environment variables in `.env.local`:
+Edit `.env.local` and set your API keys:
```bash
OPENAI_API_KEY=your_openai_key
TAVILY_API_KEY=your_tavily_key
```
-### 4. Run app locally
+To enable chat history, authentication, file upload, and other features, see [CONFIGURATION.md](./docs/CONFIGURATION.md).
+
+3. Start the dev server:
```bash
bun dev
```
-Visit http://localhost:3000 in your browser.
-
-**Note**: By default, Morphic runs without a database or authentication. To enable chat history, authentication, and other features, see [CONFIGURATION.md](./docs/CONFIGURATION.md). For Docker setup, see the [Docker Guide](./docs/DOCKER.md).
+Visit http://localhost:3000.
-## 🌐 Deploy
-
-Host your own live version of Morphic with Vercel or Docker.
+## Deploy
### Vercel
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmiurla%2Fmorphic&env=DATABASE_URL,OPENAI_API_KEY,TAVILY_API_KEY,BRAVE_SEARCH_API_KEY)
-
-**Note**: For Vercel deployments, set `ENABLE_AUTH=true` and configure Supabase authentication to secure your deployment.
-
-### Docker
-
-See the [Docker Guide](./docs/DOCKER.md) for prebuilt images, Docker Compose setup, and deployment instructions.
-
-## 👥 Contributing
-
-We welcome contributions to Morphic! Whether it's bug reports, feature requests, or pull requests, all contributions are appreciated.
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmiurla%2Fmorphic&env=OPENAI_API_KEY,TAVILY_API_KEY,ENABLE_AUTH)
-Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+## Contributing
-- How to submit issues
-- How to submit pull requests
-- Commit message conventions
-- Development setup
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started, including local development setup.
-## 📄 License
+## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 03c2df0f..752f082b 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -5,10 +5,10 @@ This guide covers the optional features and their configuration in Morphic.
## Table of Contents
- [Database](#database)
+- [AI Providers](#ai-providers)
+- [Search Providers](#search-providers)
- [Authentication](#authentication)
- [Guest Mode](#guest-mode)
-- [Search Providers](#search-providers)
-- [Additional AI Providers](#additional-ai-providers)
- [Other Features](#other-features)
## Database
@@ -25,6 +25,8 @@ DATABASE_URL=postgresql://user:password@localhost:5432/morphic
Any PostgreSQL provider works: [Neon](https://neon.tech/), [Supabase](https://supabase.com/), or a local PostgreSQL instance.
+**Docker**: Database is automatically configured — no need to set this.
+
### Running Migrations
After configuring your database, run migrations to create the necessary tables:
@@ -33,136 +35,85 @@ After configuring your database, run migrations to create the necessary tables:
bun run migrate
```
-This command applies all migrations from the `drizzle/` directory.
+This command applies all migrations from the `drizzle/` directory. Docker runs migrations automatically on startup.
-## Authentication
+## AI Providers
-By default, Morphic runs in **anonymous mode** with authentication disabled (`ENABLE_AUTH=false` in `.env.local.example`). This is ideal for personal use where all users share a single anonymous user ID.
+### Model Selection
-### Anonymous Mode (Default)
+Morphic dynamically detects available AI providers based on your API keys and displays a model selector in the UI. Set at least one provider API key to get started.
-No configuration needed. The default settings in `.env.local.example` include:
+In **Local/Docker** mode, the selected model is persisted in a cookie and used for all chat interactions including related question generation.
-```bash
-ENABLE_AUTH=false
-ANONYMOUS_USER_ID=anonymous-user
-```
-
-**⚠️ Important**: Anonymous mode is only suitable for personal, single-user environments. All chat history is shared under one user ID.
-
-### Enabling Supabase Authentication
+In **Cloud** mode (`MORPHIC_CLOUD_DEPLOYMENT=true`), models are fixed by `config/models/cloud.json` and the model selector is not shown.
-To enable user authentication with Supabase:
-
-1. Create a Supabase project at [supabase.com](https://supabase.com)
+### Supported Providers
-2. Set the following environment variables in `.env.local`:
+#### OpenAI
```bash
-ENABLE_AUTH=true
-NEXT_PUBLIC_SUPABASE_URL=[YOUR_SUPABASE_PROJECT_URL]
-NEXT_PUBLIC_SUPABASE_ANON_KEY=[YOUR_SUPABASE_ANON_KEY]
+OPENAI_API_KEY=[YOUR_API_KEY]
```
-3. Obtain your credentials from the Supabase dashboard:
- - **Project URL**: Settings → API → Project URL
- - **Anon Key**: Settings → API → Project API keys → anon/public
-
-With authentication enabled, users will need to sign up/login to use Morphic, and each user will have isolated chat history.
-
-## Guest Mode
-
-Guest mode allows users to try Morphic without creating an account. Guest sessions are ephemeral - no chat history is stored in the database.
-
-### Enabling Guest Mode
-
-Set the following environment variable:
+#### Anthropic
```bash
-ENABLE_GUEST_CHAT=true
+ANTHROPIC_API_KEY=[YOUR_API_KEY]
```
-### Guest Mode Behavior
-
-When guest mode is enabled:
+#### Google Gemini
-- **No authentication required**: Users can start chatting immediately
-- **No chat history**: Messages are not saved to the database
-- **Full context per request**: The client sends all messages with each request to maintain conversation context
-- **No URL navigation**: Guests stay on the root path (no `/search/[id]` URLs)
-- **Disabled features**:
- - File upload
- - Quality mode (forced to "Speed")
- - Chat sharing
- - Sidebar history
+```bash
+GOOGLE_GENERATIVE_AI_API_KEY=[YOUR_API_KEY]
+```
-### Rate Limiting for Guests
+#### Vercel AI Gateway
-For cloud deployments, you can limit guest usage per IP address:
+[Vercel AI Gateway](https://vercel.com/docs/ai-gateway) provides access to 200+ models through a single API.
```bash
-GUEST_CHAT_DAILY_LIMIT=10 # Maximum requests per IP per day (default: 10)
+AI_GATEWAY_API_KEY=[YOUR_AI_GATEWAY_API_KEY]
```
-Rate limiting requires Redis (Upstash) configuration:
+#### Ollama
+
+[Ollama](https://ollama.com/) enables you to run large language models locally on your own hardware.
```bash
-UPSTASH_REDIS_REST_URL=[YOUR_UPSTASH_URL]
-UPSTASH_REDIS_REST_TOKEN=[YOUR_UPSTASH_TOKEN]
+OLLAMA_BASE_URL=http://localhost:11434
```
-**Note**: Rate limiting only applies when `MORPHIC_CLOUD_DEPLOYMENT=true`. For self-hosted deployments, rate limiting is disabled by default.
-
-### Recommended Setup
-
-| Environment | Configuration |
-| -------------- | -------------------------------------------- |
-| Personal/Local | `ENABLE_AUTH=false` (anonymous mode) |
-| Public Demo | `ENABLE_GUEST_CHAT=true` with rate limiting |
-| Production | `ENABLE_AUTH=true` (Supabase authentication) |
+When configured, Ollama models are discovered dynamically and appear in the model selector.
## Search Providers
### SearXNG Configuration
-SearXNG can be used as an alternative search backend with advanced search capabilities.
+SearXNG can be used as an alternative search backend with advanced search capabilities. Docker Compose includes SearXNG automatically.
#### Basic Setup
-1. Set up SearXNG as your search provider:
-
```bash
SEARCH_API=searxng
SEARXNG_API_URL=http://localhost:8080
SEARXNG_SECRET="" # generate with: openssl rand -base64 32
```
-#### Docker Setup
-
-1. Ensure you have Docker and Docker Compose installed
-2. Two configuration files are provided in the root directory:
- - `searxng-settings.yml`: Contains main configuration for SearXNG
- - `searxng-limiter.toml`: Configures rate limiting and bot detection
-
#### Advanced Configuration
-1. Configure environment variables in your `.env.local`:
-
```bash
-# SearXNG Base Configuration
-SEARXNG_PORT=8080
-SEARXNG_BIND_ADDRESS=0.0.0.0
-SEARXNG_IMAGE_PROXY=true
-
# Search Behavior
SEARXNG_DEFAULT_DEPTH=basic # Set to 'basic' or 'advanced'
-SEARXNG_MAX_RESULTS=50 # Maximum number of results to return
-SEARXNG_ENGINES=google,bing,duckduckgo,wikipedia # Comma-separated list of search engines
-SEARXNG_TIME_RANGE=None # Time range: day, week, month, year, or None
+SEARXNG_MAX_RESULTS=50
+SEARXNG_ENGINES=google,bing,duckduckgo,wikipedia
+SEARXNG_TIME_RANGE=None # day, week, month, year, or None
SEARXNG_SAFESEARCH=0 # 0: off, 1: moderate, 2: strict
-# Rate Limiting
-SEARXNG_LIMITER=false # Enable to limit requests per IP
+# Server
+SEARXNG_PORT=8080
+SEARXNG_BIND_ADDRESS=0.0.0.0
+SEARXNG_IMAGE_PROXY=true
+SEARXNG_LIMITER=false
```
#### Advanced Search Features
@@ -170,152 +121,90 @@ SEARXNG_LIMITER=false # Enable to limit requests per IP
- `SEARXNG_DEFAULT_DEPTH`: Controls search depth
- `basic`: Standard search
- `advanced`: Includes content crawling and relevance scoring
-- `SEARXNG_MAX_RESULTS`: Maximum results to return
- `SEARXNG_CRAWL_MULTIPLIER`: In advanced mode, determines how many results to crawl
- Example: If `MAX_RESULTS=10` and `CRAWL_MULTIPLIER=4`, up to 40 results will be crawled
#### Customizing SearXNG
-You can modify `searxng-settings.yml` to:
+Modify `searxng-settings.yml` to enable/disable specific search engines, change UI settings, or adjust server options. See the [SearXNG documentation](https://docs.searxng.org/admin/settings/settings.html#settings-yml) for details.
-- Enable/disable specific search engines
-- Change UI settings
-- Adjust server options
+### Brave Search (Optional)
-Example of disabling specific engines:
+Brave Search provides enhanced support for video and image searches:
-```yaml
-engines:
- - name: wikidata
- disabled: true
+```bash
+BRAVE_SEARCH_API_KEY=[YOUR_BRAVE_SEARCH_API_KEY]
```
-For detailed configuration options, refer to the [SearXNG documentation](https://docs.searxng.org/admin/settings/settings.html#settings-yml)
-
-#### Troubleshooting
+If not configured, `type="general"` searches fall back to your configured search provider.
-- If specific search engines aren't working, try disabling them in `searxng-settings.yml`
-- For rate limiting issues, adjust settings in `searxng-limiter.toml`
-- Check Docker logs for potential configuration errors:
-
-```bash
-docker-compose logs searxng
-```
+## Authentication
-### Brave Search (Optional)
+By default, Morphic runs in **anonymous mode** (`ENABLE_AUTH=false`). This is ideal for personal, single-user environments.
-Brave Search provides enhanced support for video and image searches when used as a general search provider:
+### Anonymous Mode (Default)
```bash
-BRAVE_SEARCH_API_KEY=[YOUR_BRAVE_SEARCH_API_KEY]
-```
-
-Get your API key at: https://brave.com/search/api/
-
-**Features:**
-
-- Multiple content types in single search (web, video, image, news)
-- Optimized for multimedia content with thumbnails
-- Direct video duration and metadata support
-- Used automatically when `type="general"` is specified in search queries
-
-**Fallback Behavior:**
-If `BRAVE_SEARCH_API_KEY` is not configured, `type="general"` searches will automatically fall back to your configured optimized search provider. Video and image searches will still work but may have limited multimedia support depending on the provider.
-
-## Additional AI Providers
-
-Model selection behavior differs by deployment type:
-
-- **Cloud (`MORPHIC_CLOUD_DEPLOYMENT=true`)**: models are fixed by `config/models/cloud.json`
-- **Local/Docker (`MORPHIC_CLOUD_DEPLOYMENT=false`)**: models are fetched dynamically from provider APIs and selected in the UI; selection is persisted in `selectedModel` cookie
-
-If no user-selected model exists in Local/Docker, Morphic falls back to an internal default model.
-
-### Model Configuration
-
-Cloud model configuration uses the following structure:
-
-```json
-{
- "version": 2,
- "models": {
- "quick": {
- "id": "model-id",
- "name": "Model Name",
- "provider": "Provider Name",
- "providerId": "provider-id",
- "providerOptions": {}
- },
- "adaptive": {
- "id": "model-id",
- "name": "Model Name",
- "provider": "Provider Name",
- "providerId": "provider-id",
- "providerOptions": {}
- },
- "relatedQuestions": {
- "id": "model-id",
- "name": "Model Name",
- "provider": "Provider Name",
- "providerId": "provider-id"
- }
- }
-}
+ENABLE_AUTH=false
+ANONYMOUS_USER_ID=anonymous-user
```
-In Cloud, `quick` and `adaptive` are selected by search mode, and `relatedQuestions` is used for follow-up question generation.
-
-In Local/Docker, `cloud.json` is not used for normal chat model selection.
+All users share a single anonymous user ID. No additional configuration needed.
-### Supported Providers
+### Enabling Supabase Authentication
-#### OpenAI (Default)
+For multi-user deployments:
-```bash
-OPENAI_API_KEY=[YOUR_API_KEY]
-```
+1. Create a Supabase project at [supabase.com](https://supabase.com)
-#### Google Generative AI
+2. Set the following environment variables:
```bash
-GOOGLE_GENERATIVE_AI_API_KEY=[YOUR_API_KEY]
+ENABLE_AUTH=true
+NEXT_PUBLIC_SUPABASE_URL=[YOUR_SUPABASE_PROJECT_URL]
+NEXT_PUBLIC_SUPABASE_ANON_KEY=[YOUR_SUPABASE_ANON_KEY]
```
-#### Anthropic
+3. Obtain your credentials from the Supabase dashboard:
+ - **Project URL**: Settings > API > Project URL
+ - **Anon Key**: Settings > API > Project API keys > anon/public
-```bash
-ANTHROPIC_API_KEY=[YOUR_API_KEY]
-```
+## Guest Mode
-#### Vercel AI Gateway
+Guest mode allows users to try Morphic without creating an account. Guest sessions are ephemeral — no chat history is stored.
-[Vercel AI Gateway](https://vercel.com/docs/ai-gateway) allows you to use multiple AI providers through a single endpoint with automatic failover and load balancing.
+### Enabling Guest Mode
```bash
-AI_GATEWAY_API_KEY=[YOUR_AI_GATEWAY_API_KEY]
+ENABLE_GUEST_CHAT=true
```
-#### Ollama
+### Guest Mode Behavior
-[Ollama](https://ollama.com/) enables you to run large language models locally on your own hardware.
+- No authentication required
+- No chat history saved
+- Full context per request (client sends all messages)
+- Disabled features: file upload, chat sharing, sidebar history
+
+### Rate Limiting for Guests
-**Configuration:**
+For cloud deployments:
```bash
-OLLAMA_BASE_URL=http://localhost:11434
+GUEST_CHAT_DAILY_LIMIT=10 # Maximum requests per IP per day
+UPSTASH_REDIS_REST_URL=[YOUR_UPSTASH_URL]
+UPSTASH_REDIS_REST_TOKEN=[YOUR_UPSTASH_TOKEN]
```
-When configured, Ollama models are discovered dynamically and appear in the Local/Docker model selector.
+Rate limiting only applies when `MORPHIC_CLOUD_DEPLOYMENT=true`.
-**Important Notes:**
-
-- **Tools Capability**: Morphic requires models to support the `tools` capability for function calling. On server startup, Morphic validates configured models and logs the results. Note that even if a model reports tools support, actual tool calling performance depends on the model's capabilities and is not guaranteed.
+### Recommended Setup
-- **Validation Logs**: Check server logs on startup to verify your configured models:
- ```
- ✓ qwen3:latest (configured and tools supported)
- ✗ deepseek-r1:latest (configured but lacks tools support)
- ```
+| Environment | Configuration |
+| -------------- | -------------------------------------------- |
+| Personal/Local | `ENABLE_AUTH=false` (anonymous mode) |
+| Public Demo | `ENABLE_GUEST_CHAT=true` with rate limiting |
+| Production | `ENABLE_AUTH=true` (Supabase authentication) |
## Other Features
@@ -344,7 +233,7 @@ R2_PUBLIC_URL=[YOUR_PUBLIC_BASE_URL]
If storage variables are not configured, `/api/upload` returns `400` and uploads are disabled.
-### Alternative Fetch Tool
+### Content Extraction
Use Jina for enhanced content extraction:
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 11bde118..d59f7c42 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -1,126 +1,133 @@
# Docker Guide
-This guide covers running Morphic with Docker, including development setup, prebuilt images, and deployment options.
+## Quick Start
-## Quick Start with Docker Compose
+### Using Prebuilt Image (Recommended)
-1. Configure environment variables:
+1. Pull the latest image:
+
+```bash
+docker pull ghcr.io/miurla/morphic:latest
+```
+
+2. Configure environment:
```bash
cp .env.local.example .env.local
```
-Edit `.env.local` and set the required variables:
+Edit `.env.local` and set at least one AI provider API key:
```bash
-DATABASE_URL=postgresql://morphic:morphic@postgres:5432/morphic
OPENAI_API_KEY=your_openai_key
```
-If you switch `SEARCH_API` to `tavily`, set `TAVILY_API_KEY`.
-`BRAVE_SEARCH_API_KEY` is optional and only needed when using Brave as a dedicated general-search provider.
+Other supported providers: Anthropic (`ANTHROPIC_API_KEY`), Google (`GOOGLE_GENERATIVE_AI_API_KEY`), Ollama (`OLLAMA_BASE_URL`), Vercel AI Gateway (`AI_GATEWAY_API_KEY`).
-**Note**: Authentication is disabled by default (`ENABLE_AUTH=false` in `.env.local.example`).
-
-**Optional**: Customize PostgreSQL credentials by setting environment variables in `.env.local`:
+3. Start all services:
```bash
-POSTGRES_USER=morphic # Default: morphic
-POSTGRES_PASSWORD=morphic # Default: morphic
-POSTGRES_DB=morphic # Default: morphic
-POSTGRES_PORT=5432 # Default: 5432
+docker compose up -d
```
-2. Start the Docker containers:
+4. Visit http://localhost:3000 and select your model from the model selector.
+
+### Building from Source
+
+To build locally instead of using the prebuilt image:
```bash
-docker compose up -d
+docker compose up -d --build
```
-The application will:
+## What Docker Compose Starts
-- Start PostgreSQL 17 with health checks
-- Start Redis for SearXNG search caching
-- Wait for the database to be ready
-- Run database migrations automatically
-- Start the Morphic application
-- Start SearXNG and connect Morphic to it automatically
+- **PostgreSQL 17** - Database with automatic migrations
+- **Redis** - SearXNG search caching
+- **SearXNG** - Self-hosted search engine (no external search API key needed)
+- **Morphic** - The application
-3. Visit http://localhost:3000 in your browser.
+## Model Selection
-### Built-in Docker Defaults
+In Docker mode, Morphic dynamically detects available AI providers based on your API keys and displays a model selector in the UI. No configuration files to edit — just set your API key and pick your model.
-When running with `docker compose up -d`, Morphic is automatically configured to use internal Docker services:
+## Built-in Defaults
-- `LOCAL_REDIS_URL=redis://redis:6379`
+Docker Compose automatically sets these for you:
+
+- `ENABLE_AUTH=false` (anonymous mode)
- `SEARCH_API=searxng`
- `SEARXNG_API_URL=http://searxng:8080`
+- `LOCAL_REDIS_URL=redis://redis:6379`
- `MORPHIC_CLOUD_DEPLOYMENT=false`
-Important precedence note:
+Values in `docker-compose.yaml` take precedence over `.env.local`. To override a default:
-- Values defined in `docker-compose.yaml` under `services.morphic.environment` take precedence over `.env.local` (`env_file`) values.
-- To override a default from compose, export the variable before startup. Example:
- - `SEARCH_API=tavily docker compose up -d`
- - `SEARXNG_API_URL=http://custom-searxng:8080 docker compose up -d`
+```bash
+SEARCH_API=tavily docker compose up -d
+```
-### File Upload in Docker
+## File Upload
File upload requires externally reachable object storage. Docker Compose does not provision storage by default.
-- Required: `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_PUBLIC_URL`
-- Required (one of): `R2_ACCOUNT_ID` (Cloudflare R2) or `S3_ENDPOINT` (generic S3-compatible endpoint)
+Required environment variables:
+
+- `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_PUBLIC_URL`
+- One of: `R2_ACCOUNT_ID` (Cloudflare R2) or `S3_ENDPOINT` (generic S3-compatible)
-If these are not set, `/api/upload` returns `400` and upload is disabled.
+If these are not set, upload is disabled.
-**Note**: Database data is persisted in a Docker volume. To reset the database, run:
+## PostgreSQL Configuration
+
+Customize database credentials in `.env.local`:
```bash
-docker compose down -v # This will delete all data
+POSTGRES_USER=morphic # Default: morphic
+POSTGRES_PASSWORD=morphic # Default: morphic
+POSTGRES_DB=morphic # Default: morphic
+POSTGRES_PORT=5432 # Default: 5432
```
-## Using Prebuilt Image
-
-Prebuilt Docker images are automatically built and published to GitHub Container Registry:
+Database data is persisted in a Docker volume. To reset:
```bash
-docker pull ghcr.io/miurla/morphic:latest
+docker compose down -v # Deletes all data
```
-You can use it with docker-compose by setting the image in your `docker-compose.yaml`:
-
-```yaml
-services:
- morphic:
- image: ghcr.io/miurla/morphic:latest
- env_file: .env.local
- environment:
- DATABASE_URL: postgresql://morphic:morphic@postgres:5432/morphic
- DATABASE_SSL_DISABLED: 'true'
- ENABLE_AUTH: 'false'
- ports:
- - '3000:3000'
- depends_on:
- - postgres
- - redis
+## Enabling Authentication
+
+By default, Docker runs in anonymous mode — all users share a single anonymous user ID. This is intended for **personal, single-user local environments only**.
+
+To enable Supabase authentication for multi-user deployments:
+
+1. Set up a [Supabase](https://supabase.com/) project
+2. Build from source with the Supabase environment variables:
+
+```bash
+NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
+ENABLE_AUTH=true
```
-**Note**: The prebuilt image runs in **anonymous mode only** (`ENABLE_AUTH=false`). Supabase authentication cannot be enabled because `NEXT_PUBLIC_*` environment variables are embedded at build time by Next.js. To enable authentication or customize model configurations, you need to build from source — see [CONFIGURATION.md](./CONFIGURATION.md) for details.
+3. Build and start:
-## Building from Source
+```bash
+docker compose up -d --build
+```
-Use Docker Compose for a complete setup with PostgreSQL, Redis, and SearXNG. See the [Quick Start](#quick-start-with-docker-compose) section above.
+**Note**: The prebuilt image does not support authentication because `NEXT_PUBLIC_*` variables are embedded at build time by Next.js. You must build from source to enable authentication.
## Useful Commands
```bash
-# Start all containers in background
+# Start all containers
docker compose up -d
# Stop all containers
docker compose down
-# Stop all containers and remove volumes (deletes database data)
+# Stop and remove volumes (deletes database data)
docker compose down -v
# View logs