This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
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.
docker compose version). localhost is fine.127.0.0.1:5000 so it is not exposed unencrypted on the public IP.whoogle user (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.linux/amd64 and linux/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.
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.
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:
WHOOGLE_USER and WHOOGLE_PASS set. Without them, anyone who reaches the URL can use your instance as an open proxy to Google.127.0.0.1 binding is deliberate.WHOOGLE_CONFIG_TOR=1), expect slower searches and occasional CAPTCHA pages. The tmpfs mounts for WHOOGLE_CSP if you want the app to emit a Content-Security-Policy header.
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:
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/.