Deploying Perplexica

Introduction

Perplexica is an open-source, AI-powered search engine designed as a self-hosted alternative to Perplexity AI. It combines the power of large language models with real-time web search to provide comprehensive, sourced answers to your questions. Unlike traditional search engines that return a list of links, Perplexica synthesizes information from multiple sources and presents coherent, contextual responses.

Built with a modern tech stack including Next.js for the frontend and Node.js for the backend, Perplexica integrates with various LLM providers including OpenAI, Anthropic, Ollama, and local models. The application uses SearXNG as its metasearch engine backend to aggregate results from multiple search providers while maintaining user privacy.

Key highlights of Perplexica:

AI-Powered Search: Leverages LLMs to understand queries and synthesize comprehensive answers from web sources
Multiple Search Modes: Academic, Writing Assistant, Reddit, YouTube, Wolfram Alpha, and general web search modes
Privacy-Focused: Self-hosted with no tracking, using SearXNG for anonymous web searches
LLM Flexibility: Supports OpenAI, Anthropic, Groq, Ollama, and custom API endpoints
Source Citations: Every answer includes clickable sources for verification
Image Search: Built-in image search capabilities with AI-generated descriptions
Focus Modes: Specialized search modes optimized for different content types
Conversation History: Persistent chat history for continuing research sessions
100% Open Source: MIT licensed with active community development

This guide walks through deploying Perplexica on Klutch.sh using Docker, configuring LLM providers, and setting up the search backend for production use.

Why Deploy Perplexica on Klutch.sh

Deploying Perplexica on Klutch.sh provides several advantages for running your AI-powered search engine:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Perplexica without complex orchestration. Push to GitHub and your search engine deploys automatically.

Persistent Storage: Attach persistent volumes for conversation history, configuration, and cached data. Your search history and settings survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your search interface from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments, keeping your deployment synchronized.

Scalable Resources: Allocate CPU and memory based on your expected query volume. Start small and scale as usage grows.

Environment Variable Management: Securely store API keys for OpenAI, Anthropic, and other LLM providers through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Perplexica instance for a professional, branded search experience.

Always-On Availability: Your AI search engine remains accessible 24/7 without managing infrastructure or dealing with home network configuration.

Prerequisites

Before deploying Perplexica on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Perplexica configuration
API keys for at least one LLM provider (OpenAI, Anthropic, or Groq)
Basic familiarity with Docker and containerization concepts
(Optional) A SearXNG instance for web search functionality
(Optional) A custom domain for your Perplexica instance

Understanding Perplexica Architecture

Perplexica consists of multiple components working together:

Next.js Frontend: The web interface built with Next.js provides a clean, responsive chat interface for interacting with the search engine. It handles user input, displays results, and manages conversation history.

Node.js Backend: The backend API handles search queries, communicates with LLM providers, and orchestrates the search-to-synthesis pipeline.

SearXNG Integration: Perplexica uses SearXNG as its metasearch backend to fetch results from multiple search engines without tracking users.

LLM Providers: The AI synthesis layer connects to various LLM providers to process search results and generate comprehensive answers.

Vector Store: Optional embedding storage for enhanced semantic search capabilities using local or cloud-based vector databases.

Preparing Your Repository

To deploy Perplexica on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

perplexica-deploy/
├── Dockerfile
├── config.toml
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:20-alpine AS builder

WORKDIR /app

# Clone the Perplexica repository
RUN apk add --no-cache git && \
    git clone https://github.com/ItzCrazyKns/Perplexica.git .

# Install dependencies
RUN npm install

# Build the application
RUN npm run build

FROM node:20-alpine

WORKDIR /app

# Copy built application
COPY --from=builder /app ./

# Create data directory
RUN mkdir -p /data

# Environment variables
ENV PORT=3000
ENV NEXT_TELEMETRY_DISABLED=1

# Expose the web interface port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000 || exit 1

# Start the application
CMD ["npm", "start"]

Configuration File

Create a config.toml file for Perplexica settings:

[GENERAL]
PORT = 3001
SIMILARITY_MEASURE = "cosine"

[API_KEYS]
OPENAI = ""
GROQ = ""
ANTHROPIC = ""

[API_ENDPOINTS]
SEARXNG = "http://localhost:8080"
OLLAMA = ""

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
node_modules/
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
`OPENAI_API_KEY`	Conditional	-	OpenAI API key for GPT models
`ANTHROPIC_API_KEY`	Conditional	-	Anthropic API key for Claude models
`GROQ_API_KEY`	Conditional	-	Groq API key for fast inference
`SEARXNG_URL`	Yes	-	URL of your SearXNG instance
`OLLAMA_URL`	No	-	URL for local Ollama instance
`PORT`	No	3000	Port for the web interface

Deploying Perplexica on Klutch.sh

Once your repository is prepared, follow these steps to deploy Perplexica:

Obtain API Keys

Before deployment, obtain API keys from your preferred LLM providers:

Store these keys securely for the environment variables configuration.

Set Up SearXNG

Perplexica requires a SearXNG instance for web searches. You can either:

Deploy SearXNG as a separate app on Klutch.sh
Use a public SearXNG instance
Configure a self-hosted instance

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile config.toml .dockerignore
git commit -m "Initial Perplexica deployment configuration"
git remote add origin https://github.com/yourusername/perplexica-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “perplexica” or “ai-search”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Perplexica Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 3000 (Perplexica’s default port)

Set Environment Variables

Add the following environment variables:

Variable	Value
`OPENAI_API_KEY`	Your OpenAI API key
`ANTHROPIC_API_KEY`	Your Anthropic API key (optional)
`GROQ_API_KEY`	Your Groq API key (optional)
`SEARXNG_URL`	URL of your SearXNG instance
`NEXT_TELEMETRY_DISABLED`	`1`

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
`/data`	5 GB	Conversation history and cached data
`/app/config`	100 MB	Configuration files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the Perplexica container
Provision an HTTPS certificate

Access Perplexica

Once deployment completes, access your Perplexica instance at https://your-app-name.klutch.sh. The interface will be ready for AI-powered searches.

Initial Setup and Configuration

Configuring Search Modes

Perplexica offers multiple search modes for different use cases:

All Mode: General web search with comprehensive answers
Academic Mode: Focuses on scholarly articles and research papers
Writing Assistant: Helps with writing tasks and content generation
Reddit Mode: Searches Reddit for community discussions
YouTube Mode: Finds relevant video content
Wolfram Alpha Mode: Mathematical and computational queries

Setting Up LLM Providers

Configure your preferred LLM providers in the settings:

Access the settings through the gear icon
Select your default chat and embedding models
Configure API endpoints for each provider
Test the connection to verify functionality

Customizing the Interface

Personalize your Perplexica experience:

Choose between light and dark themes
Configure focus mode defaults
Set up keyboard shortcuts
Enable or disable search suggestions

Production Best Practices

Security Recommendations

API Key Protection: Store all API keys in Klutch.sh environment variables, never in code
Access Control: Consider adding authentication for public deployments
Rate Limiting: Configure rate limits to prevent API abuse
HTTPS Only: Always use HTTPS connections provided by Klutch.sh

Performance Optimization

Caching: Enable response caching to reduce API calls
Model Selection: Balance response quality with speed based on your needs
Resource Allocation: Monitor usage and scale resources as needed

Cost Management

Token Monitoring: Track API token usage to manage costs
Model Tiers: Use faster, cheaper models for simple queries
Local Models: Consider Ollama for unlimited local inference

Troubleshooting Common Issues

Search Results Not Loading

Symptoms: Queries timeout or return no results.

Solutions:

Verify SearXNG URL is correct and accessible
Check network connectivity between services
Review SearXNG logs for errors
Ensure SearXNG engines are configured properly

LLM API Errors

Symptoms: AI synthesis fails or returns errors.

Solutions:

Verify API keys are valid and have sufficient credits
Check rate limits on your API accounts
Review API provider status pages
Try switching to an alternative provider

Slow Response Times

Symptoms: Queries take too long to complete.

Solutions:

Use faster LLM models
Enable response streaming
Check resource allocation
Optimize SearXNG configuration

Additional Resources

Conclusion

Deploying Perplexica on Klutch.sh gives you a powerful, privacy-focused AI search engine with automatic builds, persistent storage, and secure HTTPS access. The combination of LLM synthesis and metasearch capabilities provides a compelling alternative to commercial AI search products while keeping your data under your control.

With support for multiple LLM providers and flexible search modes, Perplexica adapts to various research and information-gathering needs. Whether you’re conducting academic research, exploring technical topics, or simply want better search results, Perplexica on Klutch.sh provides the foundation for a personalized AI search experience.