This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
What Whoogle Search does and what it needs
Whoogle Search is a self-hosted metasearch front end that fetches Google results server-side and serves them without ads, JavaScript, AMP links, cookies, or IP tracking. Your browser talks only to your instance; the instance talks to Google. It supports Tor and HTTP/SOCKS proxies, custom bangs, JSON output, and basic auth.
Important status note: the upstream README states that Whoogle reached end of life on 24 Jul 2026. Google shut down the non-JavaScript search path Whoogle relied on, and the project is no longer maintained. The code and Docker images remain available under MIT, but a fresh deployment will not return live Google results today. This guide documents the last known-good Docker deployment so you can run, fork, or study it.
The project does not publish a minimum RAM figure. The official Compose file caps the container at 256 MB with a 50-process limit, which is a sensible ceiling for a single-user instance. Idle memory is small; concurrent searches and Tor routing push it toward that cap.
Prerequisites, ports, and volume constraints
- Docker Engine 24+ and the Compose v2 plugin (
docker compose version). - A hostname if you want HTTPS. For local testing,
localhostis fine. - Port 5000 is the documented container port. We bind it to
127.0.0.1:5000so it is not exposed unencrypted on the public IP. - The official image runs as the
whoogleuser (UID/GID 927) and expects writable tmpfs mounts at/config/,/var/lib/tor/, and/run/tor/. These are ephemeral by design; no named volume is required for normal operation. - Supported architectures:
linux/amd64andlinux/arm64. ARMv7 (32-bit) is not supported in v1.2.0+.
If you are testing without a domain, either SSH-tunnel to the bound port (ssh -L 5000:127.0.0.1:5000 user@host) or temporarily change the port mapping to 5000:5000 and remove it after testing.
Production Docker Compose setup
Create a project directory and drop in the Compose file. It mirrors the official structure: non-root user, dropped capabilities, no-new-privileges, tmpfs mounts, and resource limits.
mkdir -p ~/whoogle && cd ~/whoogle
cat <<'EOF' > compose.yml
services:
whoogle-search:
image: ${WHOOGLE_IMAGE:-benbusby/whoogle-search:latest}
container_name: whoogle-search
restart: unless-stopped
pids_limit: 50
mem_limit: 256mb
memswap_limit: 256mb
user: whoogle
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
tmpfs:
- /config/:size=10M,uid=927,gid=927,mode=1700
- /var/lib/tor/:size=15M,uid=927,gid=927,mode=1700
- /run/tor/:size=1M,uid=927,gid=927,mode=1700
environment:
- TZ=${TZ:-UTC}
- WHOOGLE_USER=${WHOOGLE_USER}
- WHOOGLE_PASS=${WHOOGLE_PASS}
- WHOOGLE_URL_PREFIX=${WHOOGLE_URL_PREFIX:-}
- WHOOGLE_CONFIG_TOR=${WHOOGLE_CONFIG_TOR:-0}
- WHOOGLE_PROXY_TYPE=${WHOOGLE_PROXY_TYPE:-}
- WHOOGLE_PROXY_LOC=${WHOOGLE_PROXY_LOC:-}
- WHOOGLE_PROXY_USER=${WHOOGLE_PROXY_USER:-}
- WHOOGLE_PROXY_PASS=${WHOOGLE_PROXY_PASS:-}
ports:
- 127.0.0.1:5000:5000
EOF
Now create the .env file. Generate real secrets instead of typing passwords:
cat <<EOF > .env
TZ=UTC
WHOOGLE_USER=admin
WHOOGLE_PASS=$(openssl rand -hex 16)
WHOOGLE_URL_PREFIX=
WHOOGLE_CONFIG_TOR=0
WHOOGLE_PROXY_TYPE=
WHOOGLE_PROXY_LOC=
WHOOGLE_PROXY_USER=
WHOOGLE_PROXY_PASS=
EOF
chmod 600 .env
Start the stack and confirm it is healthy:
docker compose up -d
docker compose ps
docker compose logs --tail=50 whoogle-search
curl -I http://127.0.0.1:5000/
A 401 Unauthorized from curl is expected once basic auth is enabled. Open http://127.0.0.1:5000 through an SSH tunnel to log in.
Reverse proxy, HTTPS, and first-run hardening
Whoogle is a plain HTTP app on port 5000. Put Caddy or Nginx in front of it for TLS. Because the container is bound to 127.0.0.1, the proxy must run on the same host.
Caddy (/etc/caddy/Caddyfile):
search.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:5000
}
Caddy handles X-Forwarded-Proto and WebSocket upgrades automatically. If you use Nginx instead, forward the standard headers:
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
client_max_body_size 2m;
}
Whoogle does not need large uploads, so a 2 MB body limit is generous. If you mount the app under a subpath, set WHOOGLE_URL_PREFIX (for example /whoogle) and make the proxy strip that prefix before forwarding.
First-run hardening:
- Keep
WHOOGLE_USERandWHOOGLE_PASSset. Without them, anyone who reaches the URL can use your instance as an open proxy to Google. - Do not expose port 5000 publicly. The
127.0.0.1binding is deliberate. - If you enable Tor (
WHOOGLE_CONFIG_TOR=1), expect slower searches and occasional CAPTCHA pages. The tmpfs mounts for/var/lib/tor/and/run/tor/are already sized for this. - Set
WHOOGLE_CSPif you want the app to emit a Content-Security-Policy header.
Updating, backups, and common pitfalls
Update the image and recreate the container:
cd ~/whoogle
docker compose pull
docker compose up -d
docker image prune -f
Whoogle keeps no persistent database. Configuration lives in .env, and the container's writable state is tmpfs. Back up the two files that matter:
tar czf whoogle-backup-$(date +%F).tgz compose.yml .env
If you later add a named volume for custom themes or UA caches, include it with docker run --rm -v whoogle_config:/data -v $PWD:/backup alpine tar czf /backup/config.tgz -C /data ..
Pitfalls from the docs:
-
ARMv7 hosts fail to start. The v1.2.0+ image is built only for
linux/amd64andlinux/arm64. A Raspberry Pi 2 or a 32-bit OS will pull an incompatible image. Use a 64-bit OS or pin an older tag. -
Tor mode needs a reachable control port. Setting
WHOOGLE_CONFIG_TOR=1without a working Tor control socket inside the container leaves searches hanging or failing. The official Compose file provisions the tmpfs paths Tor expects, but you still need to verify Tor is running and authenticated before relying on it. - The upstream project is archived. Do not expect bug fixes or Google compatibility patches. Treat this as a frozen deployment and plan a migration path.
Measured in our sandbox run: total memory 127.1 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 127.1 MB; published port(s) 5000; HTTP probe returned 401. The run took 90.3s including the image download. Required secret(s) WHOOGLE_PASS, WHOOGLE_USER were generated for the test run, as the tutorial instructs.
Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.
Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/self-host-whoogle-search-docker/.
Top comments (0)