Portainer Templates logo

Portainer Templates

Whoogle Whoogle

Container

OtherTools

Self-hosted, ad-free, privacy-respecting Google metasearch engine.

Image details

Pulls: 20.2M
Architecture: amd64, arm64, arm/v7
Image size: 55 MB
Latest: 1.2.4
User: benbusby
Created: May 10, 2020
Updated: 4 months ago
Status: active

Source details

Stars: 11.6k
Forks: 1k
Language: Python
License: MIT
Updated: 1 day ago
Status: archived

Configuration

Type
Container
Platform
linux
Image
benbusby/whoogle-search:latest
Ports
5001:5000/tcp
Volumes
/config : /portainer/Files/AppData/Config/Whoogle
Restart
unless-stopped

Template by novaspirit

Notes

Template created by Pi-Hosted Series
Check our Github page: https://github.com/pi-hosted/pi-hosted

Official Webpage: https://github.com/benbusby/whoogle-search
Official Docker Documentation: https://github.com/benbusby/whoogle-search#g-manual-docker

Pre-installation script must be RAN before you install: wget -qO- https://raw.githubusercontent.com/pi-hosted/pi-hosted/master/tools/install_whoogle.sh | bash



Youtube Video: Novaspirit Tech - How to Install Whoogle to replace using Google and repo notes

Standalone Install

Select an install method, to see config/commands for deploying Whoogle

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select Whoogle, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo

More install options in our documentation, or see benbusby/whoogle-search for app-specific guidance.

Whoogle Search
Latest Release License: MIT tests buildx pep8 codebeat badge Docker Pulls
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. Dependencies
  3. Install/Deploy
1. [Heroku Quick Deploy](#a-heroku-quick-deploy)
2. [Repl.it](#b-replit)
3. [Fly.io](#c-flyio)
4. [pipx](#d-pipx)
5. [pip](#e-pip)
6. [Manual](#f-manual)
7. [Docker](#g-manual-docker)
8. [Arch/AUR](#arch-linux--arch-based-distributions)
  1. Environment Variables and Configuration
  2. Usage
  3. Extra Steps
1. [Set Primary Search Engine](#set-whoogle-as-your-primary-search-engine)
2. [Prevent Downtime (Heroku Only)](#prevent-downtime-heroku-only)
3. [Manual HTTPS Enforcement](#https-enforcement)
4. [Using with Firefox Containers](#using-with-firefox-containers)
  1. Contributing
  2. FAQ
  3. Public Instances
  4. Screenshots
  5. Mirrors (read-only)
1. [GitLab](https://gitlab.com/benbusby/whoogle-search)
2. [Gogs](https://gogs.benbusby.com/benbusby/whoogle-search)

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)
  • Dark mode
  • Randomly generated User Agent
  • Easy to install/deploy
  • DDG-style bang (i.e. !<tag> <query>) searches
  • Optional location-based searching (i.e. results near \)
  • Optional NoJS mode to disable all Javascript in results

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

Dependencies

If using Heroku Quick Deploy, you can skip this section.
- Only needed if you intend on deploying the app as a Docker image
  • 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

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

A) Heroku Quick Deploy

Deploy

Note: Requires a (free) Heroku account
Provides:
  • Free deployment of app
  • Free HTTPS url (https://\.herokuapp.com)
  • Downtime after periods of inactivity \(solution\)

B) Repl.it

Run on Repl.it
Note: Requires a (free) Replit account
Provides:
  • Free deployment of app
  • Free HTTPS url (https://\.\\.repl\.co)
- Supports custom domains

C) Fly.io

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:
  • Remove the non-https service
  • Add environment variables under the [env] key
- Use fly secrets set NAME=value for more sensitive values like WHOOGLE_PASS and WHOOGLE_PROXY_PASS.

D) 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

E) 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.

F) Manual

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

G) 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).
  1. Clone and deploy the docker app using a method below:

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: - A server (I personally recommend Digital Ocean or Linode, their cheapest tiers will work fine) - Your own URL (I suppose this is optional, but recommended) - SSL certificates (free through Let's Encrypt) - A bit more experience or willingness to work through issues

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

VariableDescription
WHOOGLEDOTENVLoad environment variables in whoogle.env
WHOOGLEUSERThe username for basic auth. WHOOGLEPASS must also be set if used.
WHOOGLEPASSThe password for basic auth. WHOOGLEUSER must also be set if used.
WHOOGLEPROXYUSERThe username of the proxy server.
WHOOGLEPROXYPASSThe password of the proxy server.
WHOOGLEPROXYTYPEThe type of the proxy server. Can be "socks5", "socks4", or "http".
WHOOGLEPROXYLOCThe location of the proxy server (host or ip).
EXPOSEPORTThe port where Whoogle will be exposed.
HTTPSONLYEnforce HTTPS. (See here)
WHOOGLEALTTWThe twitter.com alternative to use when site alternatives are enabled in the config.
WHOOGLEALTYTThe youtube.com alternative to use when site alternatives are enabled in the config.
WHOOGLEALTIGThe instagram.com alternative to use when site alternatives are enabled in the config.
WHOOGLEALTRDThe reddit.com alternative to use when site alternatives are enabled in the config.
WHOOGLEALTTLThe Google Translate alternative to use. This is used for all "translate " searches.

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.
VariableDescription
WHOOGLECONFIGDISABLEHide config from UI and disallow changes to config by client
WHOOGLECONFIGCOUNTRYFilter results by hosting country
WHOOGLECONFIGLANGUAGESet interface language
WHOOGLECONFIGSEARCHLANGUAGESet search result language
WHOOGLECONFIGBLOCKBlock websites from search results (use comma-separated list)
WHOOGLECONFIGTHEMESet theme mode (light, dark, or system)
WHOOGLECONFIGSAFEEnable safe searches
WHOOGLECONFIGALTSUse social media site alternatives (nitter, invidious, etc)
WHOOGLECONFIGTORUse Tor routing (if available)
WHOOGLECONFIGNEWTABAlways open results in new tab
WHOOGLECONFIGVIEWIMAGEEnable View Image option
WHOOGLECONFIGGETONLYSearch using GET requests only
WHOOGLECONFIGURLThe root url of the instance (https://<your url>/)
WHOOGLECONFIGSTYLEThe 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

Serve Whoogle on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxying whoogle.example.com to http://whoogle:5000

Add this to your Caddyfile

whoogle.example.com {
	reverse_proxy http://whoogle:5000
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs whoogle
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:5001 failed: port is already allocated", something else on your server is using that port.

  • Find what's using it: sudo ss -tlnp | grep :5001
  • Stop the other service, or pick a different host port. In 5001:5000 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

  • Use your server's real IP: http://your-server-ip:5001. The 0.0.0.0 link Portainer shows isn't a real address.
  • Give it a minute after first deploy, whoogle can take a while to initialise.
  • Make sure your firewall allows the port, e.g. sudo ufw allow 5001

Permission denied on volumes

If the logs show "permission denied", the app can't write to its data folder on the host.

  • Fix the ownership: sudo chown -R 1000:1000 /portainer/Files/AppData/Config/Whoogle

Image won't pull

Test the pull directly on the host: docker pull benbusby/whoogle-search:latest

  • "manifest unknown" means the tag no longer exists. This template uses latest, so try pinning a specific version instead.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • This image supports: amd64, arm64, arm/v7
  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

  • Check the logs right after a restart, the last few lines before it died are the useful ones.
  • Get the exit code with docker inspect whoogle --format '{{.State.ExitCode}}'
  • Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Upstream project is archived

The developers have archived benbusby/whoogle-search, so bugs and security issues won't be fixed.

  • It'll keep working for now, but consider the similar apps below for a maintained alternative.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A single container

Whoogle runs as one container, the simplest kind of app here. Just the one image to pull and nothing else wired up alongside it.

The app image

An image is the app packed up ready to go, everything Whoogle needs bundled into one download. This template pulls benbusby/whoogle-search:latest, which Docker fetches once (about 55 MB) and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. Whoogle's comes from Docker Hub, published by benbusby.

Version tags

The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Newest right now is 1.2.4. Pin a specific tag if you would rather stay on one version.

Which machines it runs on

Every image is built for particular CPU types. This one ships for amd64, arm64, arm/v7, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.

Ports

A port is the door the app answers on. A mapping like 5001:5000 means it's reachable on port 5001 of your server, where the left number is yours to change and the right one belongs to the app. It opens:

  • 5001:5000

Volumes

A volume is where Whoogle keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

  • /config from /portainer/Files/AppData/Config/Whoogle on the host

Restart policy

The restart policy here is unless-stopped, so Docker restarts Whoogle after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Networking

Nothing custom is set, so Whoogle sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container whoogle. That's what you'll spot in the containers list and use in commands like docker logs whoogle.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Open source license

Whoogle is open source, released under the MIT license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Whoogle up. Add the template list to Portainer once, then deploying Whoogle is a click rather than a wall of config.