SearXNG Local Deployment and Configuration

CherryStudio supports web search via SearXNG. SearXNG is an open-source project that can be deployed locally or on a server, so its configuration differs slightly from other setups that require an API provider.

SearXNG project link:SearXNG

Advantages of SearXNG

• Open-source and free, no API required

• Relatively strong privacy

• Highly customizable

Local deployment

1. Direct Docker deployment

Because SearXNG does not require complex environment configuration, you do not need docker compose. You only need to provide an idle port to deploy it, so the fastest way is to deploy it directly with Docker by pulling the image.

1. Download, install, and configure docker

After installation, choose an image storage path:

2. Search for and pull the SearXNG image

Enter in the search bar searxng :

Pull the image:

3. Run the image

After the pull succeeds, go to the images page:

Select the pulled image and click Run:

Open the settings to configure:

Take 8085 port as an example:

After it runs successfully, click the link to open the SearXNG frontend interface:

If this page appears, deployment was successful:

Server deployment

Given that installing Docker on Windows is rather troublesome, users can deploy SearXNG on a server and share it with others. Unfortunately, SearXNG itself does not currently support authentication, so others may be able to discover and abuse your deployed instance through technical means.

For this reason, Cherry Studio now supports configuring HTTP Basic Authentication (RFC7617). If you want to expose your deployed SearXNG to the public internet, pleasemake sureto configure HTTP Basic Authentication through a reverse proxy such as Nginx. A brief tutorial is provided below; basic Linux operations knowledge is required.

Deploy SearXNG

Similarly, Docker is still used for deployment. Assuming you have already followed theofficial tutorialto install the latest version of Docker CE on your server, the following one-stop command applies to a fresh installation on a Debian system:

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 very small, you can set this to false
export IMAGE_PROXY=true

# Modify the 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 an existing local Nginx, remove the following. By default, we do not 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 an existing local Nginx, remove the above. By default, we do not 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
    # By default it maps to port 8080 on the host machine. If you want to listen on 8000, change it 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 an existing local Nginx, remove the following
  caddy-data:
  caddy-config:
# If you don't need Caddy and want to reuse an existing 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 a server control panel application, such as BaoTa Panel or 1Panel, please refer to its documentation to add a website and configure an Nginx reverse proxy. Then find where you can edit the Nginx configuration file and modify it according to 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, you should have 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 a reverse proxy through the panel, the default location block looks like this
    location / {
        # Just add the following two lines inside the location block; keep the rest unchanged.
        # This example assumes your configuration file is stored under the /etc/nginx/conf.d/ directory.
        # If you use BaoTa, it is probably stored in a /www-like directory; take note of that.
        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 configuration file is saved under /etc/nginx/conf.d we will save 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 is also fine).

At this point, open the webpage and you should be prompted to enter a username and password. Enter the username and password you set earlier to see whether you can successfully enter the SearXNG search page and use this to check whether the configuration is correct.

Cherry Studio related configuration

After SearXNG has been successfully deployed locally or on a server, the next step is the CherryStudio-related configuration.

Go to the web search settings page and select Searxng:

If you directly enter the locally deployed link and find that verification fails, don't worry:

Because after direct deployment, the JSON return type is not configured by default, so data cannot be obtained and the configuration file needs to be modified.

Go back to Docker, go to the Files tab, and find the tagged folder in the image:

After expanding it, continue scrolling down and you will find another tagged folder:

Continue expanding and find the settings.yml configuration file:

Click to open the file editor:

Find line 78, where you can see that the only type is html

Add the json type, save it, and run the image again

Go back to Cherry Studio to verify again; verification succeeds:

The address can be entered as local: http://localhost : port number or as the Docker address:http://host.docker.internal : port number

If the user followed the previous example to deploy on a server and configured the reverse proxy correctly, JSON return type has already been enabled. After entering the address and verifying, because HTTP Basic Authentication has been configured for the reverse proxy, the verification should return error code 401:

Configure HTTP Basic Authentication on the client side and enter the username and password you just set:

Verify, and it should succeed.

Other configurations

At this point, SearXNG already has the default ability to search the web. If you need to customize the search engines, you need to configure them yourself

Note that the preferences here do not affect the configuration used when calling the large model

If you need to configure the search engines used for large model calls, set it in the configuration file:

Refer to the configuration language:

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

Common causes of verification failure

The return format does not include JSON

Add json to the return formats in the configuration file:

Search engine not configured correctly

Cherry Studio will by default choose engines whose categories include both web and general for search. By default it will select engines such as Google, which fail because mainland China cannot access sites like Google directly. Adding the following configuration forces searxng to use the baidu engine, which solves the problem:

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

Access rate too fast

The limiter configuration in searxng blocks API access. Try setting it to false in the settings: