hassio-addons/whoogle/DOCS.md

## Environment Variables
There are a few optional environment variables available for customizing a Whoogle instance. These can be set manually, or copied into `whoogle.env` and enabled for your preferred deployment method:

- Local runs: Set `WHOOGLE_DOTENV=1` before running
- With `docker-compose`: Uncomment the `env_file` option
- With `docker build/run`: Add `--env-file ./whoogle.env` to your command

| Variable             | Description                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------- |
| WHOOGLE_DOTENV       | Load environment variables in `whoogle.env`                                               |
| WHOOGLE_USER         | The username for basic auth. WHOOGLE_PASS must also be set if used.                       |
| WHOOGLE_PASS         | The password for basic auth. WHOOGLE_USER must also be set if used.                       |
| WHOOGLE_PROXY_USER   | The username of the proxy server.                                                         |
| WHOOGLE_PROXY_PASS   | The password of the proxy server.                                                         |
| WHOOGLE_PROXY_TYPE   | The type of the proxy server. Can be "socks5", "socks4", or "http".                       |
| WHOOGLE_PROXY_LOC    | The location of the proxy server (host or ip).                                            |
| EXPOSE_PORT          | The port where Whoogle will be exposed.                                                   |
| HTTPS_ONLY           | Enforce HTTPS. (See [here](https://github.com/benbusby/whoogle-search#https-enforcement)) |
| WHOOGLE_ALT_TW       | The twitter.com alternative to use when site alternatives are enabled in the config.      |
| WHOOGLE_ALT_YT       | The youtube.com alternative to use when site alternatives are enabled in the config.      |
| WHOOGLE_ALT_IG       | The instagram.com alternative to use when site alternatives are enabled in the config.    |
| WHOOGLE_ALT_RD       | The reddit.com alternative to use when site alternatives are enabled in the config.       |
| WHOOGLE_ALT_TL       | The Google Translate alternative to use. This is used for all "translate ____" searches.  |
| WHOOGLE_ALT_MD       | The medium.com alternative to use when site alternatives are enabled in the config.       |
| WHOOGLE_AUTOCOMPLETE | Controls visibility of autocomplete/search suggestions. Default on -- use '0' to disable  |
| WHOOGLE_MINIMAL      | Remove everything except basic result cards from all search queries.                      |
| WHOOGLE_CSP          | Sets a default set of 'Content-Security-Policy' headers                                   |
| WHOOGLE_RESULTS_PER_PAGE          | Set the number of results per page                                   |

### Config Environment Variables
These environment variables allow setting default config values, but can be overwritten manually by using the home page config menu. These allow a shortcut for destroying/rebuilding an instance to the same config state every time.

| Variable                       | Description                                                     |
| ------------------------------ | --------------------------------------------------------------- |
| WHOOGLE_CONFIG_DISABLE         | Hide config from UI and disallow changes to config by client    |
| WHOOGLE_CONFIG_COUNTRY         | Filter results by hosting country                               |
| WHOOGLE_CONFIG_LANGUAGE        | Set interface language                                          |
| WHOOGLE_CONFIG_SEARCH_LANGUAGE | Set search result language                                      |
| WHOOGLE_CONFIG_BLOCK           | Block websites from search results (use comma-separated list)   |
| WHOOGLE_CONFIG_THEME           | Set theme mode (light, dark, or system)                         |
| WHOOGLE_CONFIG_SAFE            | Enable safe searches                                            |
| WHOOGLE_CONFIG_ALTS            | Use social media site alternatives (nitter, invidious, etc)     |
| WHOOGLE_CONFIG_NEAR            | Restrict results to only those near a particular city           |
| WHOOGLE_CONFIG_TOR             | Use Tor routing (if available)                                  |
| WHOOGLE_CONFIG_NEW_TAB         | Always open results in new tab                                  |
| WHOOGLE_CONFIG_VIEW_IMAGE      | Enable View Image option                                        |
| WHOOGLE_CONFIG_GET_ONLY        | Search using GET requests only                                  |
| WHOOGLE_CONFIG_URL             | The root url of the instance (`https://<your url>/`)            |
| WHOOGLE_CONFIG_STYLE           | The custom CSS to use for styling (should be single line)       |

## Usage
Same as most search engines, with the exception of filtering by time range.

To filter by a range of time, append ":past <time>" to the end of your search, where <time> can be `hour`, `day`, `month`, or `year`. Example: `coronavirus updates :past hour`

## Extra Steps
### Set Whoogle as your primary search engine
*Note: If you're using a reverse proxy to run Whoogle Search, make sure the "Root URL" config option on the home page is set to your URL before going through these steps.*

Browser settings:
  - Firefox (Desktop)
    - Version 89+
      - Navigate to your app's url, right click the address bar, and select "Add Search Engine".
    - Previous versions
      - Navigate to your app's url, and click the 3 dot menu in the address bar. At the bottom, there should be an option to "Add Search Engine".
    - Once you've added the new search engine, open your Firefox Preferences menu, click "Search" in the left menu, and use the available dropdown to select "Whoogle" from the list.
    - **Note**: If your Whoogle instance uses Firefox Containers, you'll need to [go through the steps here](#using-with-firefox-containers) to get it working properly.
  - Firefox (iOS)
    - In the mobile app Settings page, tap "Search" within the "General" section. There should be an option titled "Add Search Engine" to select. It should prompt you to enter a title and search query url - use the following elements to fill out the form:
      - Title: "Whoogle"
      - URL: `http[s]://\<your whoogle url\>/search?q=%s`
  - Firefox (Android)
    - Version <79.0.0
      - Navigate to your app's url
      - Long-press on the search text field
      - Click the "Add Search Engine" menu item
        - Select a name and click ok
      - Click the 3 dot menu in the top right
      - Navigate to the settings menu and select the "Search" sub-menu
      - Select Whoogle and press "Set as default"
    - Version >=79.0.0
      - Click the 3 dot menu in the top right
      - Navigate to the settings menu and select the "Search" sub-menu
      - Click "Add search engine"
      - Select the 'Other' radio button
        - Name: "Whoogle"
        - Search string to use: `https://\<your whoogle url\>/search?q=%s`
  - [Alfred](https://www.alfredapp.com/) (Mac OS X)
	  1. Go to `Alfred Preferences` > `Features` > `Web Search` and click `Add Custom Search`. Then configure these settings
		   - Search URL: `https://\<your whoogle url\>/search?q={query}
		   - Title: `Whoogle for '{query}'` (or whatever you want)
		   - Keyword: `whoogle`

	  2. Go to `Default Results` and click the `Setup fallback results` button. Click `+` and add Whoogle, then  drag it to the top.
  - Chrome/Chromium-based Browsers
    - Automatic
      - Visit the home page of your Whoogle Search instance -- this may automatically add the search engine to your list of search engines. If not, you can add it manually.
    - Manual
      - Under search engines > manage search engines > add, manually enter your Whoogle instance details with a `<whoogle url>/search?q=%s` formatted search URL.