benbusby/whoogle-search
Self-hosted, ad-free, privacy-respecting metasearch engine
10M+
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
!<tag> <query>
) searches*If deployed to a remote server, or configured to send requests through a VPN, Tor, proxy, etc.
If using Heroku Quick Deploy, you can skip this section.
libcurl4-openssl-dev
and libssl-dev
brew install openssl curl-openssl
sudo apt-get install -y libcurl4-openssl-dev libssl-dev
pacman -S curl openssl
There are a few different ways to begin using the app, depending on your preferences:
Note: Requires a (free) Heroku account
Provides:
Note: Requires a (free) Replit account
Provides:
You will need a Fly.io account to do this. Fly requires a credit card to deploy anything, but you can have up to 3 shared-CPU VMs running full-time each month for free.
Install the CLI:
curl -L https://fly.io/install.sh | sh
Deploy your app
fly apps create --org personal --port 5000
# Choose a name and the Image builder
# Enter `benbusby/whoogle-search:latest` as the image name
fly deploy
Your app is now available at https://<app-name>.fly.dev
.
You can customize the fly.toml
:
[env]
key
fly secrets set NAME=value
for more sensitive values like WHOOGLE_PASS
and WHOOGLE_PROXY_PASS
.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 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.
Note: Content-Security-Policy
headers are already sent by Whoogle -- you don't/shouldn't need to apply a CSP header yourself
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 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=nitter.net
#Environment=WHOOGLE_ALT_YT=invidious.snopyta.org
#Environment=WHOOGLE_ALT_IG=bibliogram.art/u
#Environment=WHOOGLE_ALT_RD=libredd.it
#Environment=WHOOGLE_ALT_TL=lingva.ml
# Load values from dotenv only
#Environment=WHOOGLE_DOTENV=1
Type=simple
User=root
WorkingDirectory=<whoogle_directory>
ExecStart=<whoogle_directory>/venv/bin/python3 -um app --host 0.0.0.0 --port 5000
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
sudo usermod -aG docker yourusername
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).Docker CLI
Note: For ARM machines, use the buildx-experimental
Docker tag.
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 Chaotic-AUR.
Using your own server, or alternative container deployment
There are other methods for deploying docker containers that are well outlined in this article, but there are too many to describe set up for each here. Generally it should be about the same amount of effort as the Heroku deployment.
Depending on your preferences, you can also deploy the app yourself on your own infrastructure. This route would require a few extra steps:
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:
WHOOGLE_DOTENV=1
before runningdocker-compose
: Uncomment the env_file
optiondocker build/run
: Add --env-file ./whoogle.env
to your commandVariable | 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. |
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_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) |
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
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:
http[s]://\<your whoogle url\>/search?q=%s
https://\<your whoogle url\>/search?q=%s
Go to Alfred Preferences
> Features
> Web Search
and click Add Custom Search
. Then configure these settings
Whoogle for '{query}'
(or whatever you want)whoogle
Go to Default Results
and click the Setup fallback results
button. Click +
and add Whoogle, then drag it to the top.
<whoogle url>/search?q=%s
formatted search URL.Part of the deal with Heroku's free tier is that you're allocated 550 hours/month (meaning it can't stay active 24/7), and the app is temporarily shut down after 30 minutes of inactivity. Once it becomes inactive, any Whoogle searches will still work, but it'll take an extra 10-15 seconds for the app to come back online before displaying the result, which can be frustrating if you're in a hurry.
A good solution for this is to set up a simple cronjob on any device at your home that is consistently powered on and connected to the internet (in my case, a PiHole worked perfectly). All the device needs to do is fetch app content on a consistent basis to keep the app alive in whatever ~17 hour window you want it on (17 hrs * 31 days = 527, meaning you'd still have 23 leftover hours each month if you searched outside of your target window).
For instance, adding */20 7-23 * * * curl https://<your heroku app name>.herokuapp.com > /home/<username>/whoogle-refresh
will fetch the home page of the app every 20 minutes between 7am and midnight, allowing for downtime from midnight to 7am. And again, this wouldn't be a hard limit - you'd still have plenty of remaining hours of uptime each month in case you were searching after this window has closed.
Since the instance is destroyed and rebuilt after inactivity, config settings will be reset once the app enters downtime. If you have configuration settings active that you'd like to keep between periods of downtime (like dark mode for example), you could instead add */20 7-23 * * * curl -d "dark=1" -X POST https://<your heroku app name>.herokuapp.com/config > /home/<username>/whoogle-refresh
to keep these settings more or less permanent, and still keep the app from entering downtime when you're using it.
Only needed if your setup requires Flask to redirect to HTTPS on its own -- generally this is something that doesn't need to be handled by Whoogle Search.
Note: You should have your own domain name and an https certificate in order for this to work properly.
Root URL
configuration on the home page begins with https://
and not http://
--build-arg use_https=1
to your run command--https-only
flag to the end of the whoogle-search
commandrun
script: Modify the script locally to include the --https-only
flag at the end of the python run commandUnfortunately, Firefox Containers do not currently pass through POST
requests (the default) to the engine, and Firefox caches the opensearch template on initial page load. To get around this, you can take the following steps to get it working as expected:
GET Requests Only
in Whoogle configdocker pull benbusby/whoogle-search