Manual installation

Install and run Perplexica without Docker on your local machine

While Docker is recommended, you can install Perplexica manually on your system. This method gives you more control but requires managing dependencies yourself.

Manual installation requires you to set up and maintain SearxNG separately. Using Docker simplifies this process considerably.

Prerequisites

Before starting, ensure you have:

• Node.js 24.5.0 or later
• npm or yarn package manager
• A running SearxNG instance with JSON format enabled
• Python 3 (for SearxNG)

Installation steps

1. Set up SearxNG

   Install SearxNG and configure it to allow JSON format. Make sure the Wolfram Alpha search engine is enabled in your SearxNG settings.

   For SearxNG installation instructions, visit the SearxNG documentation.

2. Clone the repository

   git clone https://github.com/ItzCrazyKns/Perplexica.git
   cd Perplexica
   
3. Install dependencies

   npm i
   

   This will install all required packages from package.json:15398.

4. Build the application

   npm run build
   

   This runs Next.js build process to compile the application.

5. Start the application

   npm run start
   

   The application will start on port 3000 by default.

6. Configure settings

   Open your browser and navigate to http://localhost:3000 to complete the setup. Configure your settings including:

   • API keys for your chosen LLM provider
   • Model selection
   • SearxNG URL (should point to your SearxNG instance)

Running in development mode

For development or testing purposes, you can run Perplexica in development mode:

npm run dev

This runs the Next.js development server with hot reloading enabled.

SearxNG configuration

Your SearxNG instance must be properly configured for Perplexica to work:

Enable JSON format

In your SearxNG settings.yml, ensure JSON format is enabled:

search:
  formats:
    - html
    - json

Enable Wolfram Alpha

Perplexica uses Wolfram Alpha for mathematical calculations and data lookups. Enable it in your SearxNG configuration.

Network accessibility

If running SearxNG on the same machine, ensure it’s accessible at the URL you configure in Perplexica (typically http://localhost:8080).

Managing the application

Start production server

npm run start

File locations

When running manually, Perplexica stores data in the following locations:

• Application data: ./data/ directory in your installation folder
• Uploaded files: ./uploads/ directory (created automatically)
• Database: SQLite database in ./data/

Make sure these directories have appropriate read/write permissions for the user running the application.

Production deployment

For production deployments without Docker:

1. Use a process manager like PM2 to keep the application running:

npm install -g pm2
pm2 start npm --name "perplexica" -- start
pm2 save
pm2 startup

2. Set up a reverse proxy (nginx or Apache) to handle SSL/TLS

3. Configure firewall rules to allow traffic on port 3000 (or your chosen port)

4. Ensure SearxNG is running as a system service

Next steps

Updating

Keep your installation current

Troubleshooting

Resolve common issues