{"slug": "self-host-whoogle-search-with-docker-private-metasearch", "title": "Self-Host Whoogle Search with Docker: Private Metasearch", "summary": "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.", "body_md": "This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.\n\nWhoogle 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.\n\n**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.\n\nThe 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.\n\n`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+.\nIf 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.\n\nCreate 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.\n\n```\nmkdir -p ~/whoogle && cd ~/whoogle\ncat <<'EOF' > compose.yml\nservices:\n  whoogle-search:\n    image: ${WHOOGLE_IMAGE:-benbusby/whoogle-search:latest}\n    container_name: whoogle-search\n    restart: unless-stopped\n    pids_limit: 50\n    mem_limit: 256mb\n    memswap_limit: 256mb\n    user: whoogle\n    security_opt:\n      - no-new-privileges:true\n    cap_drop:\n      - ALL\n    tmpfs:\n      - /config/:size=10M,uid=927,gid=927,mode=1700\n      - /var/lib/tor/:size=15M,uid=927,gid=927,mode=1700\n      - /run/tor/:size=1M,uid=927,gid=927,mode=1700\n    environment:\n      - TZ=${TZ:-UTC}\n      - WHOOGLE_USER=${WHOOGLE_USER}\n      - WHOOGLE_PASS=${WHOOGLE_PASS}\n      - WHOOGLE_URL_PREFIX=${WHOOGLE_URL_PREFIX:-}\n      - WHOOGLE_CONFIG_TOR=${WHOOGLE_CONFIG_TOR:-0}\n      - WHOOGLE_PROXY_TYPE=${WHOOGLE_PROXY_TYPE:-}\n      - WHOOGLE_PROXY_LOC=${WHOOGLE_PROXY_LOC:-}\n      - WHOOGLE_PROXY_USER=${WHOOGLE_PROXY_USER:-}\n      - WHOOGLE_PROXY_PASS=${WHOOGLE_PROXY_PASS:-}\n    ports:\n      - 127.0.0.1:5000:5000\nEOF\n```\n\nNow create the `.env` file. Generate real secrets instead of typing passwords:\n\n```\ncat <<EOF > .env\nTZ=UTC\nWHOOGLE_USER=admin\nWHOOGLE_PASS=$(openssl rand -hex 16)\nWHOOGLE_URL_PREFIX=\nWHOOGLE_CONFIG_TOR=0\nWHOOGLE_PROXY_TYPE=\nWHOOGLE_PROXY_LOC=\nWHOOGLE_PROXY_USER=\nWHOOGLE_PROXY_PASS=\nEOF\nchmod 600 .env\n```\n\nStart the stack and confirm it is healthy:\n\n```\ndocker compose up -d\ndocker compose ps\ndocker compose logs --tail=50 whoogle-search\ncurl -I http://127.0.0.1:5000/\n```\n\nA `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.\n\nWhoogle 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.\n\n**Caddy** (`/etc/caddy/Caddyfile`):\n\n```\nsearch.example.com {\n    encode zstd gzip\n    reverse_proxy 127.0.0.1:5000\n}\n```\n\nCaddy handles `X-Forwarded-Proto` and WebSocket upgrades automatically. If you use Nginx instead, forward the standard headers:\n\n```\nlocation / {\n    proxy_pass http://127.0.0.1:5000;\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    proxy_set_header X-Forwarded-Proto $scheme;\n    proxy_http_version 1.1;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection \"upgrade\";\n    client_max_body_size 2m;\n}\n```\n\nWhoogle 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.\n\n**First-run hardening:**\n\n`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.\nUpdate the image and recreate the container:\n\n```\ncd ~/whoogle\ndocker compose pull\ndocker compose up -d\ndocker image prune -f\n```\n\nWhoogle keeps no persistent database. Configuration lives in `.env`, and the container's writable state is tmpfs. Back up the two files that matter:\n\n```\ntar czf whoogle-backup-$(date +%F).tgz compose.yml .env\n```\n\nIf 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 .`.\n\n**Pitfalls from the docs:**\n\n**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.\n\n*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.*\n\n*Originally published with full interactive benchmark metrics and server sizing notes at [https://vpsfolio.pages.dev/self-host-whoogle-search-docker/](https://vpsfolio.pages.dev/self-host-whoogle-search-docker/).*", "url": "https://wpnews.pro/news/self-host-whoogle-search-with-docker-private-metasearch", "canonical_source": "https://dev.to/gongkang/self-host-whoogle-search-with-docker-private-metasearch-aec", "published_at": "2026-11-21 03:02:07+00:00", "updated_at": "2026-11-21 03:11:56.515411+00:00", "lang": "en", "topics": ["ai-search", "developer-tools"], "entities": ["Whoogle Search", "Google", "Docker", "Caddy", "Nginx", "Tor"], "also_reported_by": [], "takeaway": "Whoogle's server-side scraping approach broke once Google removed its non-JavaScript search path, so self-hosted metasearch front ends that depend on scraping Google HTML need a maintained upstream or a different retrieval path.", "recommendation": {"advice": "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.", "playbook": "production-ops", "playbook_url": "https://wpnews.pro/playbooks/production-ops"}, "alternates": {"html": "https://wpnews.pro/news/self-host-whoogle-search-with-docker-private-metasearch", "markdown": "https://wpnews.pro/news/self-host-whoogle-search-with-docker-private-metasearch.md", "text": "https://wpnews.pro/news/self-host-whoogle-search-with-docker-private-metasearch.txt", "jsonld": "https://wpnews.pro/news/self-host-whoogle-search-with-docker-private-metasearch.jsonld"}}