# Self-Host Whoogle Search with Docker: Private Metasearch

> Source: <https://dev.to/gongkang/self-host-whoogle-search-with-docker-private-metasearch-aec>
> Published: 2026-11-21 03:02:07+00:00

**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 the playbook "Running AI in production": <https://wpnews.pro/playbooks/production-ops>

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/](https://vpsfolio.pages.dev/self-host-whoogle-search-docker/).*
