> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ItzCrazyKns/Perplexica/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Comprehensive guide for installing Perplexica using Docker or manual setup methods.

Perplexica can be installed in two ways: using Docker (recommended) or manually without Docker. This guide covers both methods in detail.

## Docker installation (recommended)

Using Docker is the recommended approach as it simplifies setup, manages dependencies automatically, and includes a bundled SearxNG instance.

### Quick start with Docker

The simplest way to run Perplexica is with a single Docker command:

```bash theme={null}
docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:latest
```

This command:

* Pulls the latest Perplexica image with bundled SearxNG
* Creates a persistent volume for your data and uploaded files
* Exposes the application on [http://localhost:3000](http://localhost:3000)

<Info>
  The image includes both Perplexica and SearxNG, so no additional configuration is required. Simply open [http://localhost:3000](http://localhost:3000) and configure your AI provider settings in the setup screen.
</Info>

### Using your own SearxNG instance

If you already have SearxNG running, use the slim version:

```bash theme={null}
docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:slim-latest
```

<Warning>
  **Important SearxNG requirements:**

  * JSON format must be enabled in settings
  * Wolfram Alpha search engine must be enabled
</Warning>

Replace `http://your-searxng-url:8080` with your actual SearxNG URL, then configure your AI provider settings at [http://localhost:3000](http://localhost:3000).

### Building from source with Docker

For more control or development purposes, you can build Perplexica from source:

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/ItzCrazyKns/Perplexica.git
    cd Perplexica
    ```
  </Step>

  <Step title="Build the Docker image">
    ```bash theme={null}
    docker build -t perplexica .
    ```

    The Dockerfile uses a multi-stage build process:

    * **Builder stage**: Installs dependencies and builds the Next.js application
    * **Production stage**: Sets up SearxNG and the runtime environment
  </Step>

  <Step title="Run the container">
    ```bash theme={null}
    docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data --name perplexica perplexica
    ```
  </Step>

  <Step title="Configure and start using">
    Access Perplexica at [http://localhost:3000](http://localhost:3000) and configure your settings in the setup screen.
  </Step>
</Steps>

<Note>
  After the containers are built, you can start Perplexica directly from Docker Desktop or Docker CLI without opening a terminal.
</Note>

### Using Docker Compose

For a more declarative approach, use Docker Compose:

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/ItzCrazyKns/Perplexica.git
    cd Perplexica
    ```
  </Step>

  <Step title="Start with Docker Compose">
    ```bash theme={null}
    docker-compose up -d
    ```

    The `docker-compose.yaml` configuration:

    ```yaml theme={null}
    services:
      perplexica:
        image: itzcrazykns1337/perplexica:latest
        build:
          context: .
        ports:
          - '3000:3000'
        volumes:
          - data:/home/perplexica/data
        restart: unless-stopped

    volumes:
      data:
        name: 'perplexica-data'
    ```
  </Step>

  <Step title="Access the application">
    Open [http://localhost:3000](http://localhost:3000) in your browser and complete the setup.
  </Step>
</Steps>

## Manual installation (without Docker)

For users who prefer not to use Docker or need more control over the installation:

<Warning>
  Manual installation requires more setup and maintenance. Docker is recommended for most users.
</Warning>

<Steps>
  <Step title="Install and configure SearxNG">
    1. Install SearxNG following the [official documentation](https://docs.searxng.org/)
    2. Enable JSON format in SearxNG settings
    3. Enable the Wolfram Alpha search engine
    4. Note your SearxNG URL (e.g., `http://localhost:8080`)
  </Step>

  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/ItzCrazyKns/Perplexica.git
    cd Perplexica
    ```
  </Step>

  <Step title="Install dependencies">
    Perplexica requires Node.js 24.5.0 or later. Install dependencies using npm:

    ```bash theme={null}
    npm i
    ```

    Key dependencies include:

    * **Next.js 16.0.7**: React framework for the web interface
    * **Ollama 0.6.3**: Local LLM integration
    * **OpenAI 6.9.0**: Cloud AI provider support
    * **Drizzle ORM**: Database management with SQLite
    * **Transformers**: Hugging Face model support
  </Step>

  <Step title="Build the application">
    ```bash theme={null}
    npm run build
    ```

    This compiles the Next.js application and prepares it for production.
  </Step>

  <Step title="Start the application">
    ```bash theme={null}
    npm run start
    ```

    The application will start on [http://localhost:3000](http://localhost:3000).
  </Step>

  <Step title="Configure settings">
    Open [http://localhost:3000](http://localhost:3000) in your browser and configure:

    * AI provider (Ollama, OpenAI, Claude, Groq, etc.)
    * API keys and endpoints
    * SearxNG URL
    * Other preferences
  </Step>
</Steps>

<Info>
  For development, use `npm run dev` to start the development server with hot reloading.
</Info>

## AI provider configuration

Perplexica supports multiple AI providers. Configure them in the setup screen after installation.

### Ollama (local LLMs)

For privacy-focused users who want to run models locally:

<Tabs>
  <Tab title="Windows">
    1. Install Ollama from [ollama.ai](https://ollama.ai)
    2. Pull your desired model:
       ```bash theme={null}
       ollama pull llama2
       ```
    3. In Perplexica settings:
       * API URL: `http://host.docker.internal:11434`
       * Model: `llama2` (or your chosen model)
       * API Key: Any value (required but not validated)
  </Tab>

  <Tab title="Mac">
    1. Install Ollama from [ollama.ai](https://ollama.ai)
    2. Pull your desired model:
       ```bash theme={null}
       ollama pull llama2
       ```
    3. In Perplexica settings:
       * API URL: `http://host.docker.internal:11434`
       * Model: `llama2` (or your chosen model)
       * API Key: Any value (required but not validated)
  </Tab>

  <Tab title="Linux">
    1. Install Ollama from [ollama.ai](https://ollama.ai)
    2. Expose Ollama to the network by editing `/etc/systemd/system/ollama.service`:
       ```ini theme={null}
       Environment="OLLAMA_HOST=0.0.0.0:11434"
       ```
    3. Reload and restart:
       ```bash theme={null}
       systemctl daemon-reload
       systemctl restart ollama
       ```
    4. Pull your desired model:
       ```bash theme={null}
       ollama pull llama2
       ```
    5. In Perplexica settings:
       * API URL: `http://<your-private-ip>:11434`
       * Model: `llama2` (or your chosen model)
       * API Key: Any value (required but not validated)
    6. Ensure port 11434 is not blocked by your firewall
  </Tab>
</Tabs>

### OpenAI

1. Get an API key from [platform.openai.com](https://platform.openai.com)
2. In Perplexica settings:
   * API Key: Your OpenAI API key
   * Model: `gpt-4`, `gpt-3.5-turbo`, or other available models
   * API URL: `https://api.openai.com/v1`

### Anthropic Claude

1. Get an API key from [console.anthropic.com](https://console.anthropic.com)
2. In Perplexica settings:
   * API Key: Your Anthropic API key
   * Model: `claude-3-opus`, `claude-3-sonnet`, `claude-3-haiku`
   * Configure the endpoint in settings

### Groq

1. Get an API key from [console.groq.com](https://console.groq.com)
2. In Perplexica settings:
   * API Key: Your Groq API key
   * Model: Available Groq models
   * Configure the endpoint in settings

### Google Gemini

1. Get an API key from [ai.google.dev](https://ai.google.dev)
2. In Perplexica settings:
   * API Key: Your Google API key
   * Model: `gemini-pro` or other available models
   * Configure the endpoint in settings

### Local OpenAI-compatible servers

For custom LLM servers that implement the OpenAI API:

1. Ensure your server runs on `0.0.0.0` (not `127.0.0.1`)
2. Note the port and model name
3. In Perplexica settings:
   * API URL: Your server URL (e.g., `http://localhost:8000`)
   * Model: The exact model name loaded by your server
   * API Key: Any value (required even if your server doesn't validate it)

## Troubleshooting

### Ollama connection errors

<AccordionGroup>
  <Accordion title="Connection refused">
    **Symptoms**: "Failed to connect to Ollama" error

    **Solutions**:

    1. Verify Ollama is running:
       ```bash theme={null}
       ollama list
       ```
    2. Check the API URL matches your OS:
       * Windows/Mac: `http://host.docker.internal:11434`
       * Linux: `http://<your-private-ip>:11434`
    3. For Linux, ensure Ollama is exposed to the network:
       ```bash theme={null}
       # Edit /etc/systemd/system/ollama.service
       Environment="OLLAMA_HOST=0.0.0.0:11434"

       # Reload and restart
       systemctl daemon-reload
       systemctl restart ollama
       ```
    4. Check firewall settings - port 11434 must be accessible
  </Accordion>

  <Accordion title="Model not found">
    **Symptoms**: "Model not found" error

    **Solutions**:

    1. List available models:
       ```bash theme={null}
       ollama list
       ```
    2. Pull the model if missing:
       ```bash theme={null}
       ollama pull llama2
       ```
    3. Ensure the model name in Perplexica settings matches exactly
  </Accordion>
</AccordionGroup>

### Local OpenAI-compatible server errors

<AccordionGroup>
  <Accordion title="No chat model providers configured">
    **Symptoms**: Perplexica says no providers are configured

    **Solutions**:

    1. Server must run on `0.0.0.0`, not `127.0.0.1`
    2. Verify the port matches your API URL
    3. Confirm the exact model name loaded by your server
    4. Put any value in the API key field (cannot be empty)
  </Accordion>
</AccordionGroup>

### Lemonade connection errors

<AccordionGroup>
  <Accordion title="Cannot connect to Lemonade">
    **Symptoms**: "Failed to connect to Lemonade" error

    **Solutions**:

    1. Check your Lemonade API URL in settings
    2. Set the correct URL based on your OS:
       * Windows/Mac: `http://host.docker.internal:8000`
       * Linux: `http://<your-private-ip>:8000`
    3. Ensure Lemonade server is running and accessible
    4. Verify Lemonade accepts connections from all interfaces (`0.0.0.0`), not just localhost
    5. Check that port 8000 (or your custom port) is not blocked
  </Accordion>
</AccordionGroup>

### Docker issues

<AccordionGroup>
  <Accordion title="Port already in use">
    **Symptoms**: "Port 3000 is already allocated" error

    **Solutions**:

    1. Check what's using port 3000:
       ```bash theme={null}
       docker ps
       ```
    2. Use a different port:
       ```bash theme={null}
       docker run -d -p 8080:3000 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:latest
       ```
       Then access at `http://localhost:8080`
  </Accordion>

  <Accordion title="Container won't start">
    **Symptoms**: Container exits immediately

    **Solutions**:

    1. Check logs:
       ```bash theme={null}
       docker logs perplexica
       ```
    2. Verify Docker has enough resources (memory, disk space)
    3. Try removing and recreating:
       ```bash theme={null}
       docker rm perplexica
       docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:latest
       ```
  </Accordion>
</AccordionGroup>

## Advanced configuration

### Using as a search engine

Add Perplexica as a custom search engine in your browser:

1. Open your browser's settings
2. Navigate to 'Search Engines'
3. Add a new site search:
   * URL: `http://localhost:3000/?q=%s`
   * (Replace `localhost:3000` with your domain if hosted remotely)
4. Set a keyword (e.g., `perplexica` or `px`)

Now you can search directly from your browser's address bar!

### Exposing to network

Perplexica runs on Next.js and works on your local network by default. For external access:

1. **Port forwarding**: Configure your router to forward port 3000
2. **Reverse proxy**: Use Nginx or Caddy for HTTPS and custom domains
3. **Cloud deployment**: See the one-click deployment options below

### One-click deployment

Deploy Perplexica to the cloud with these providers:

* **Sealos**: [Deploy to Sealos](https://usw.sealos.io/?openapp=system-template%3FtemplateName%3Dperplexica)
* **RepoCloud**: [Deploy to RepoCloud](https://repocloud.io/details/?app_id=267)
* **ClawCloud**: [Run on ClawCloud](https://template.run.claw.cloud/?referralCode=U11MRQ8U9RM4\&openapp=system-fastdeploy%3FtemplateName%3Dperplexica)
* **Hostinger**: [Deploy on Hostinger](https://www.hostinger.com/vps/docker-hosting?compose_url=https://raw.githubusercontent.com/ItzCrazyKns/Perplexica/refs/heads/master/docker-compose.yaml)

## Next steps

<CardGroup cols={2}>
  <Card title="API integration" icon="code" href="https://github.com/ItzCrazyKns/Perplexica/tree/master/docs/API/SEARCH.md">
    Integrate Perplexica's search engine into your applications
  </Card>

  <Card title="Architecture" icon="diagram-project" href="https://github.com/ItzCrazyKns/Perplexica/tree/master/docs/architecture/README.md">
    Learn how Perplexica works under the hood
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="https://github.com/ItzCrazyKns/Perplexica/blob/master/CONTRIBUTING.md">
    Contribute to Perplexica's development
  </Card>

  <Card title="Community" icon="discord" href="https://discord.gg/EFwsmQDgAu">
    Join the Discord community for help and discussions
  </Card>
</CardGroup>