cd /news/ai-search/self-host-whoogle-search-with-docker… · home › topics › ai-search › article
[ARTICLE · art-173608] src=dev.to ↗ pub= topic=ai-search verified=true sentiment=· neutral

Self-Host Whoogle Search with Docker: Private Metasearch

A developer documented a Docker Compose deployment for Whoogle Search, a self-hosted metasearch front end that fetches Google results server-side and strips ads, JavaScript, AMP links, cookies and IP tracking. The guide notes that Whoogle reached end of life on 24 July 2026 after Google shut down the non-JavaScript search path it relied on, so the code and MIT-licensed Docker images remain available for running, forking or study but no longer return live Google results. The setup uses a non-root user, dropped capabilities, no-new-privileges, tmpfs mounts and a 256 MB memory cap, with basic auth, Tor and proxy options and a Caddy or Nginx reverse proxy for TLS.

recommendation

Before deploying a self-hosted search front end, confirm the upstream is maintained and its retrieval path still works; Whoogle's images run but return no live results since its EOL on 24 July 2026.

more in playbook: Running AI in production
by read4 min views5 publishedNov 21, 2026

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/.

── more in #ai-search 4 stories · sorted by recency
── more on @whoogle search 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/self-host-whoogle-se…] indexed:0 read:4min 2026-11-21 · —