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)
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 " to the end of your search, where 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 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 (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.