SearXNG Local Deployment and Configuration

CherryStudio supports web search through SearXNG. SearXNG is an open-source project that can be deployed locally or on a server, so its configuration differs somewhat from other methods that require API providers.

SearXNG project link:SearXNG

Advantages of SearXNG

• Open-source and free, no API required

• Relatively high privacy

• Highly customizable

Local deployment

1. Direct deployment with Docker

Because SearXNG does not require complicated environment configuration and can be deployed by simply providing an available port without docker compose, the fastest way is to pull the image directly with Docker for deployment.

1. Install, download and configure docker

After installation, choose a path to store images:

2. Search for and pull the SearXNG image

Enter in the search bar searxng :

Pull image:

3. Run the image

After successfully pulling, go to images page:

Select the pulled image and click Run:

Open the settings to configure:

Using 8085 port as an example:

After successful run, click the link to open SearXNG's frontend:

If you see this page it means the deployment succeeded:

Server deployment

Since installing Docker on Windows can be somewhat troublesome, users can deploy SearXNG on a server and even share it with others. Unfortunately, SearXNG itself does not currently support authentication, which means others could discover and abuse your deployed instance via technical means.

To address this, Cherry Studio currently supports configuring HTTP Basic Authentication (RFC7617), so if a user wants to expose their deployed SearXNG to the public internet, pleasebe sureto configure HTTP Basic Authentication via a reverse proxy like Nginx. Below is a brief tutorial that requires basic Linux administration knowledge.

Deploying SearXNG

Similarly, continue to use Docker for deployment. Assuming you have followed theofficial guideto install the latest Docker CE on your server, below is a one-stop command set suitable for a fresh Debian installation:

sudo apt update
sudo apt install git -y

# Pull the official repository
cd /opt
git clone https://github.com/searxng/searxng-docker.git
cd /opt/searxng-docker

# If your server bandwidth is small, you can set this to false
export IMAGE_PROXY=true

# Modify configuration file
cat <<EOF > /opt/searxng-docker/searxng/settings.yml
# see https://docs.searxng.org/admin/settings/settings.html#settings-use-default-settings
use_default_settings: true
server:
  # base_url is defined in the SEARXNG_BASE_URL environment variable, see .env and docker-compose.yml
  secret_key: $(openssl rand -hex 32)
  limiter: false  # can be disabled for a private instance
  image_proxy: $IMAGE_PROXY
ui:
  static_use_hash: true
redis:
  url: redis://redis:6379/0
search:
  formats:
    - html
    - json
EOF

If you need to change the local listening port or reuse an existing local nginx, you can edit the docker-compose.yaml file, refer to the following:

version: "3.7"

services:
# If you don't need Caddy and want to reuse your local Nginx, remove the below. By default we don't need Caddy.
  caddy:
    container_name: caddy
    image: docker.io/library/caddy:2-alpine
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data:rw
      - caddy-config:/config:rw
    environment:
      - SEARXNG_HOSTNAME=${SEARXNG_HOSTNAME:-http://localhost}
      - SEARXNG_TLS=${LETSENCRYPT_EMAIL:-internal}
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"
# If you don't need Caddy and want to reuse your local Nginx, remove the above. By default we don't need Caddy.
  redis:
    container_name: redis
    image: docker.io/valkey/valkey:8-alpine
    command: valkey-server --save 30 1 --loglevel warning
    restart: unless-stopped
    networks:
      - searxng
    volumes:
      - valkey-data2:/data
    cap_drop:
      - ALL
    cap_add:
      - SETGID
      - SETUID
      - DAC_OVERRIDE
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"

  searxng:
    container_name: searxng
    image: docker.io/searxng/searxng:latest
    restart: unless-stopped
    networks:
      - searxng
    # Default maps to host port 8080. If you want to listen on 8000 change to "127.0.0.1:8000:8080"
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_BASE_URL=https://${SEARXNG_HOSTNAME:-localhost}/
      - UWSGI_WORKERS=${SEARXNG_UWSGI_WORKERS:-4}
      - UWSGI_THREADS=${SEARXNG_UWSGI_THREADS:-4}
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"

networks:
  searxng:

volumes:
# If you don't need Caddy and want to reuse your local Nginx, remove the below
  caddy-data:
  caddy-config:
# If you don't need Caddy and want to reuse your local Nginx, remove the above
  valkey-data2:

Run docker compose up -d to start. Run docker compose logs -f searxng to view the logs.

Deploy Nginx reverse proxy and HTTP Basic Authentication

If you use some server panel programs like BT Panel or 1Panel, refer to their documentation to add a site and configure an nginx reverse proxy, then find where to edit the nginx config and modify it with the example below:

server
{
    listen 443 ssl;

    # This line is your hostname
    server_name search.example.com;

    # index index.html;
    # root /data/www/default;

    # If SSL is configured there should be these two lines
    ssl_certificate    /path/to/your/cert/fullchain.pem;
    ssl_certificate_key    /path/to/your/cert/privkey.pem;

    # HSTS
    # add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload";

    # By default when configuring reverse proxy through a panel, the default location block looks like this
    location / {
        # You only need to add the following two lines in the location block; leave the rest as is.
        # This example assumes your config file is stored under /etc/nginx/conf.d/.
        # If it is BT Panel it might be stored under /www or similar, so pay attention.
        auth_basic "Please enter your username and password";
        auth_basic_user_file /etc/nginx/conf.d/search.htpasswd;

        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_protocol_addr;
        proxy_pass http://127.0.0.1:8000;
        client_max_body_size 0;
    }

    # access_log  ...;
    # error_log  ...;
}

Assuming the Nginx config files are saved under /etc/nginx/conf.d we will store the password file in the same directory.

Run the command (replace example_name,example_password with the username and password you want to set):

echo "example_name:$(openssl passwd -5 'example_password')" > /etc/nginx/conf.d/search.htpasswd

Restart Nginx (reloading the configuration also works).

At this point you can open the webpage; it should prompt you for a username and password. Enter the username and password you set earlier to see if you can successfully access the SearXNG search page to verify the configuration.

Cherry Studio related configuration

After SearXNG is deployed locally or on the server, next is CherryStudio configuration.

Go to the web search settings page and select Searxng:

If entering the locally deployed link directly fails verification, don't worry:

because the direct deployment by default does not have the json return type configured, so it cannot retrieve data and you need to modify the configuration file.

Return to Docker, go to the Files tab and find the folder with the tag inside the image:

After expanding, continue to scroll down and you will find another folder with a tag:

Continue expanding and find settings.yml configuration file:

Click to open the file editor:

Find line 78, you can see only html type is present

Add the json type, save, and restart the image

Return to Cherry Studio to validate again; the validation succeeds:

The address can be filled with local: http://localhost : port number or you can fill in the docker address:http://host.docker.internal : port number

If the user followed the earlier example to deploy on a server and correctly configured the reverse proxy and enabled the json return type, after entering the address and validating, because HTTP Basic Authentication is configured on the reverse proxy, the validation should return a 401 error code:

Configure HTTP Basic Authentication on the client by entering the username and password set earlier:

Validate; it should validate successfully.

Other settings

At this point SearXNG has default internet search capability. If you need to customize search engines you must configure them yourself

Note that these preferences do not affect the configuration used when large models make calls

To configure the search engines used by large model calls, set them in the configuration file:

Configuration language reference:

If the content is too long and difficult to edit directly, you can copy it to a local IDE, modify it there, and then paste it back into the configuration file.

Common reasons for validation failure

The return formats did not include json

Add json to the return formats in the configuration file:

Search engines not configured correctly

Cherry Studio will by default select engines whose categories include web and general. By default it selects engines like Google, which cannot be accessed directly from mainland China and will fail. Add the following configuration to force searxng to use the baidu engine to resolve the issue:

use_default_settings:
  engines:
    keep_only:
      - baidu
engines:
  - name: baidu
    engine: baidu 
    categories: 
      - web
      - general
    disabled: false

Access rate too fast

searxng's limiter configuration is blocking API access; try setting it to false in the settings: