whoogle-search

Get Google search results, but without any ads, JavaScript, AMP links, cookies, or IP address tracking. Easily deployable in one click as a Docker app, and customizable with a single config file. Quick and simple to implement as a primary search engine replacement on both desktop and mobile.

Contents

1. Features
2. Install/Deploy Options
   1. Heroku Quick Deploy
   2. Render.com
   3. Repl.it
   4. Fly.io
   5. Koyeb
   6. pipx
   7. pip
   8. Manual
   9. Docker
   10. Arch/AUR
   11. Helm/Kubernetes
3. Environment Variables and Configuration
4. Usage
5. Extra Steps
   1. Set Primary Search Engine
   2. Custom Redirecting
   3. Custom Bangs
   4. Prevent Downtime (Heroku Only)
   5. Manual HTTPS Enforcement
   6. Using with Firefox Containers
   7. Reverse Proxying
      1. Nginx
6. Contributing
7. FAQ
8. Public Instances
9. Screenshots

Features

• No ads or sponsored content
• No JavaScript*
• No cookies**
• No tracking/linking of your personal IP address***
• No AMP links
• No URL tracking tags (i.e. utm=%s)
• No referrer header
• Tor and HTTP/SOCKS proxy support
• Autocomplete/search suggestions
• POST request search and suggestion queries (when possible)
• View images at full res without site redirect (currently mobile only)
• Light/Dark/System theme modes (with support for custom CSS theming)
• Randomly generated User Agent
• Easy to install/deploy
• DDG-style bang (i.e. !<tag> <query>) searches
• User-defined custom bangs
• Optional location-based searching (i.e. results near <city>)
• Optional NoJS mode to view search results in a separate window with JavaScript blocked

^{*No third party JavaScript. Whoogle can be used with JavaScript disabled, but if enabled, uses JavaScript for things like presenting search suggestions.}

^{**No third party cookies. Whoogle uses server side cookies (sessions) to store non-sensitive configuration settings such as theme, language, etc. Just like with JavaScript, cookies can be disabled and not affect Whoogle's search functionality.}

^{***If deployed to a remote server, or configured to send requests through a VPN, Tor, proxy, etc.}

Install

There are a few different ways to begin using the app, depending on your preferences:

Heroku Quick Deploy

Provides:

• Easy Deployment of App
• A HTTPS url (https://<your app name>.herokuapp.com)

Notes:

• Requires a PAID Heroku Account.
• Sometimes has issues with auto-redirecting to https. Make sure to navigate to the https version of your app before adding as a default search engine.

Render

Create an account on render.com and import the Whoogle repo with the following settings:

• Runtime: Python 3
• Build Command: pip install -r requirements.txt
• Run Command: ./run

Repl.it

Note: Requires a (free) Replit account

Provides:

• Free deployment of app
• Free HTTPS url (https://<app name>.<username>.repl.co)
  • Supports custom domains
• Downtime after periods of inactivity (solution)

Fly.io

You will need a Fly.io account to deploy Whoogle. The free allowances are enough for personal use.

Install the CLI: https://fly.io/docs/hands-on/installing/

Deploy the app

flyctl auth login
flyctl launch --image benbusby/whoogle-search:latest

The first deploy won't succeed because the default internal_port is wrong. To fix this, open the generated fly.toml file, set services.internal_port to 5000 and run flyctl launch again.

Your app is now available at https://<app-name>.fly.dev.

Koyeb

Use one of the following guides to install Whoogle on Koyeb:

1. Using GitHub: https://www.koyeb.com/docs/quickstart/deploy-with-git
2. Using Docker: https://www.koyeb.com/docs/quickstart/deploy-a-docker-application

pipx

Persistent install:

pipx install git+https://github.com/benbusby/whoogle-search.git

Sandboxed temporary instance:

pipx run --spec git+https://github.com/benbusby/whoogle-search.git whoogle-search

pip

pip install whoogle-search

$ whoogle-search --help
usage: whoogle-search [-h] [--port <port number>] [--host <ip address>] [--debug] [--https-only] [--userpass <username:password>]
                      [--proxyauth <username:password>] [--proxytype <socks4|socks5|http>] [--proxyloc <location:port>]

Whoogle Search console runner

optional arguments:
  -h, --help            Show this help message and exit
  --port <port number>  Specifies a port to run on (default 5000)
  --host <ip address>   Specifies the host address to use (default 127.0.0.1)
  --debug               Activates debug mode for the server (default False)
  --https-only          Enforces HTTPS redirects for all requests
  --userpass <username:password>
                        Sets a username/password basic auth combo (default None)
  --proxyauth <username:password>
                        Sets a username/password for a HTTP/SOCKS proxy (default None)
  --proxytype <socks4|socks5|http>
                        Sets a proxy type for all connections (default None)
  --proxyloc <location:port>
                        Sets a proxy location for all connections (default None)

See the available environment variables for additional configuration.

Manual

Note: Content-Security-Policy headers can be sent by Whoogle if you set WHOOGLE_CSP.

Dependencies

• Python3
• libcurl4-openssl-dev and libssl-dev
  • macOS: brew install openssl curl-openssl
  • Ubuntu: sudo apt-get install -y libcurl4-openssl-dev libssl-dev
  • Arch: pacman -S curl openssl

Install

Clone the repo and run the following commands to start the app in a local-only environment:

git clone https://github.com/benbusby/whoogle-search.git
cd whoogle-search
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./run

See the available environment variables for additional configuration.

systemd Configuration

After building the virtual environment, you can add something like the following to /lib/systemd/system/whoogle.service to set up a Whoogle Search systemd service:

[Unit]
Description=Whoogle

[Service]
# Basic auth configuration, uncomment to enable
#Environment=WHOOGLE_USER=<username>
#Environment=WHOOGLE_PASS=<password>
# Proxy configuration, uncomment to enable
#Environment=WHOOGLE_PROXY_USER=<proxy username>
#Environment=WHOOGLE_PROXY_PASS=<proxy password>
#Environment=WHOOGLE_PROXY_TYPE=<proxy type (http|https|proxy4|proxy5)
#Environment=WHOOGLE_PROXY_LOC=<proxy host/ip>
# Site alternative configurations, uncomment to enable
# Note: If not set, the feature will still be available
# with default values.
#Environment=WHOOGLE_ALT_TW=farside.link/nitter
#Environment=WHOOGLE_ALT_YT=farside.link/invidious
#Environment=WHOOGLE_ALT_RD=farside.link/libreddit
#Environment=WHOOGLE_ALT_MD=farside.link/scribe
#Environment=WHOOGLE_ALT_TL=farside.link/lingva
#Environment=WHOOGLE_ALT_IMG=farside.link/rimgo
#Environment=WHOOGLE_ALT_WIKI=farside.link/wikiless
#Environment=WHOOGLE_ALT_IMDB=farside.link/libremdb
#Environment=WHOOGLE_ALT_QUORA=farside.link/quetre
# Load values from dotenv only
#Environment=WHOOGLE_DOTENV=1
Type=simple
User=<username>
# If installed as a package, add:
ExecStart=<python_install_dir>/python3 <whoogle_install_dir>/whoogle-search --host 127.0.0.1 --port 5000
# For example:
# ExecStart=/usr/bin/python3 /home/my_username/.local/bin/whoogle-search --host 127.0.0.1 --port 5000
# Otherwise if running the app from source, add:
ExecStart=<whoogle_repo_dir>/run
# For example:
# ExecStart=/var/www/whoogle-search/run
WorkingDirectory=<whoogle_repo_dir>
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=3
SyslogIdentifier=whoogle

[Install]
WantedBy=multi-user.target

Then,

sudo systemctl daemon-reload
sudo systemctl enable whoogle
sudo systemctl start whoogle

Tor Configuration optional

If routing your request through Tor you will need to make the following adjustments. Due to the nature of interacting with Google through Tor we will need to be able to send signals to Tor and therefore authenticate with it.

There are two authentication methods, password and cookie. You will need to make changes to your torrc:

• Cookie

  1. Uncomment or add the following lines in your torrc:

     • ControlPort 9051
     • CookieAuthentication 1
     • DataDirectoryGroupReadable 1
     • CookieAuthFileGroupReadable 1

  2. Make the tor auth cookie readable:

     • This is assuming that you are using a dedicated user to run whoogle. If you are using a different user replace whoogle with that user.

     1. chmod tor:whoogle /var/lib/tor
     2. chmod tor:whoogle /var/lib/tor/control_auth_cookie

  3. Restart the tor service:

     • systemctl restart tor

  4. Set the Tor environment variable to 1, WHOOGLE_CONFIG_TOR. Refer to the Environment Variables section for more details.

     • This may be added in the systemd unit file or env file WHOOGLE_CONFIG_TOR=1

• Password

  1. Run this command:

     • tor --hash-password {Your Password Here}; put your password in place of {Your Password Here}.
     • Keep the output of this command, you will be placing it in your torrc.
     • Keep the password input of this command, you will be using it later.

  2. Uncomment or add the following lines in your torrc:

     • ControlPort 9051
     • HashedControlPassword {Place output here}; put the output of the previous command in place of {Place output here}.

  3. Now take the password from the first step and place it in the control.conf file within the whoogle working directory, ie. misc/tor/control.conf

     • If you want to place your password file in a different location set this location with the WHOOGLE_TOR_CONF environment variable. Refer to the Environment Variables section for more details.

  4. Heavily restrict access to control.conf to only be readable by the user running whoogle:

     • chmod 400 control.conf

  5. Finally set the Tor environment variable and use password variable to 1, WHOOGLE_CONFIG_TOR and WHOOGLE_TOR_USE_PASS. Refer to the Environment Variables section for more details.

     • These may be added to the systemd unit file or env file:
       • WHOOGLE_CONFIG_TOR=1
       • WHOOGLE_TOR_USE_PASS=1

Manual (Docker)

1. Ensure the Docker daemon is running, and is accessible by your user account

• To add user permissions, you can execute sudo usermod -aG docker yourusername
• Running docker ps should return something besides an error. If you encounter an error saying the daemon isn't running, try sudo systemctl start docker (Linux) or ensure the docker tool is running (Windows/macOS).

2. Clone and deploy the docker app using a method below:

Docker CLI

Through Docker Hub:

docker pull benbusby/whoogle-search
docker run --publish 5000:5000 --detach --name whoogle-search benbusby/whoogle-search:latest

or with docker-compose:

git clone https://github.com/benbusby/whoogle-search.git
cd whoogle-search
docker-compose up

or by building yourself:

git clone https://github.com/benbusby/whoogle-search.git
cd whoogle-search
docker build --tag whoogle-search:1.0 .
docker run --publish 5000:5000 --detach --name whoogle-search whoogle-search:1.0

Optionally, you can also enable some of the following environment variables to further customize your instance:

docker run --publish 5000:5000 --detach --name whoogle-search \
  -e WHOOGLE_USER=username \
  -e WHOOGLE_PASS=password \
  -e WHOOGLE_PROXY_USER=username \
  -e WHOOGLE_PROXY_PASS=password \
  -e WHOOGLE_PROXY_TYPE=socks5 \
  -e WHOOGLE_PROXY_LOC=ip \
  whoogle-search:1.0

And kill with: docker rm --force whoogle-search

Using Heroku CLI

heroku login
heroku container:login
git clone https://github.com/benbusby/whoogle-search.git
cd whoogle-search
heroku create
heroku container:push web
heroku container:release web
heroku open

This series of commands can take a while, but once you run it once, you shouldn't have to run it again. The final command, heroku open will launch a tab in your web browser, where you can test out Whoogle and even set it as your primary search engine. You may also edit environment variables from your app’s Settings tab in the Heroku Dashboard.

Arch Linux & Arch-based Distributions

There is an AUR package available, as well as a pre-built and daily updated package available at