# 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](https://github.com/searxng/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](https://www.docker.com/)

<figure><img src="/files/9e82971de41d3a740f0e21428878c883f4d4cc55" alt=""><figcaption></figcaption></figure>

After installation, choose an image storage path:

<figure><img src="/files/348b09a1687298bb753c31dac0ee22e4d4764633" alt=""><figcaption></figcaption></figure>

#### 2. Search for and pull the SearXNG image

Enter in the search bar **searxng** :

<figure><img src="/files/4acf1aeeb48f5fee250401bc704c7d96039f6321" alt=""><figcaption></figcaption></figure>

Pull the image:

<figure><img src="/files/a77e2405fa5420b036799c9347bcd2427881189f" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/1d69c465ba041fbe1642316831d1677750752fe3" alt=""><figcaption></figcaption></figure>

#### 3. Run the image

After the pull succeeds, go to the **images** page:

<figure><img src="/files/9ec04b96e854d4798a7472c5fe3e954037d15f1e" alt=""><figcaption></figcaption></figure>

Select the pulled image and click Run:

<figure><img src="/files/4ee5345730a7214c153c5607b0903002bb0ec462" alt=""><figcaption></figcaption></figure>

Open the settings to configure:

<figure><img src="/files/9c1fd22e823f1148738e3c41ba1fb315220c208e" alt=""><figcaption></figcaption></figure>

Take `8085` port as an example:

<figure><img src="/files/858f2e89d489a52b69c94c3c929246d36e419576" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/0323e422883c1a83d5ab5040876db535cc2a8b2e" alt=""><figcaption></figcaption></figure>

If this page appears, deployment was successful:

<figure><img src="/files/b7f46bb5934d2c444a8d056abe1d948b7e5eed71" alt=""><figcaption></figcaption></figure>

## 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)](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Guides/Authentication). If you want to expose your deployed SearXNG to the public internet, please**make sure**to 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 the[official tutorial](https://docs.docker.com/engine/install)to install the latest version of Docker CE on your server, the following one-stop command applies to a fresh installation on a Debian system:

```bash
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:

```yaml
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:

```conf
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):

```bash
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.

<figure><img src="/files/556c7a0f904ddcd7ea89a597a21a3b88c4a95488" alt=""><figcaption></figcaption></figure>

## 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:

<figure><img src="/files/3a353f7c13612ceeaab7e16c22d2ec8bf6a380c7" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/f5e19aa349b33f2bf89f806722ca9e0661528888" alt=""><figcaption></figcaption></figure>

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:

<figure><img src="/files/bbecf19a041e64524456e2fb7e72137122acf92d" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/7e1227138bd651fede24b40d2215c617e736bbbb" alt=""><figcaption></figcaption></figure>

Continue expanding and find the **settings.yml** configuration file:

<figure><img src="/files/0782b9e91f9369f7b1d72c2c56f928673a92fafa" alt=""><figcaption></figcaption></figure>

Click to open the file editor:

<figure><img src="/files/aa8f9d92869a2c06bdc95d961bd572872a79fae6" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/fb0a7b5cc91865165fd87fedeb3cfbb30bd88115" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/50ecb6d99939b8b920e32b4d5f6cd5dd7a6e898f" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/2d916252cf79747966168c74eba90475c8342603" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/4e90ca769884ac32a86fb556fc988001092596cc" alt=""><figcaption></figcaption></figure>

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:

<figure><img src="/files/ffa5546330be32f58fd686bf98c7dd7a3e59754d" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/7d4027cb7fe167a4ae1e48b56feeb2216a695643" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/5228c8b07611211e8baa636da7e4a73bf899dc62" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/0482298bc45b2d635badd94a6f0770e9848be3cf" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/a3d3d8151d823238a33993fcade06974574a2030" alt=""><figcaption></figcaption></figure>

Refer to the configuration language:

<figure><img src="/files/28f6fb99c118e030ac3ff2854894269fc45324b3" alt=""><figcaption></figcaption></figure>

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:

<figure><img src="/files/f7bf7b98494381439b525a695a1c8496f3e330b4" alt=""><figcaption></figcaption></figure>

### 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:

<figure><img src="/files/f765a271281448682a6fa769fb254320b612fe29" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cherry-ai.com/docs/en-us/pre-basic/websearch/searxng.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.