How to Self-Host Whoogle in 2026: Privacy, Rate Limits and Proxy Settings

A Whoogle container can be green while the job users care about is broken. For Whoogle, that hidden failure is usually that the upstream blocks the IP or proxy environment variables are incorrect. This guide treats “submit searches with normal and privacy settings, verify result links, test an upstream proxy and trigger the chosen rate limit” as the acceptance test and builds the deployment backward from that result.

Whoogle has a specific role in the stack: Google search results without ads, tracking or client JavaScript. The production question is therefore not whether port 5000 answers once, but whether state, dependencies and the public address continue to agree after a restart, update and restore.

Define success for Whoogle first

A useful Whoogle diagram shows the public route, private port 5000, state boundary and every supporting requirement. Mark which arrows carry credentials and which are ordinary user traffic. The external requirement for Whoogle is outbound HTTPS access and a stable server IP that search providers accept. Test outbound DNS, TLS and provider behavior without publishing another inbound service.

Prove the diagram with one real action: submit searches with normal and privacy settings, verify result links, test an upstream proxy and trigger the chosen rate limit. The likely pressure comes from upstream search blocking, server IP reputation, concurrent queries and proxy latency; monitor that path rather than treating all HTTP requests as equal.

Route Whoogle without lying about HTTPS

Avoid temporary and permanent public origins for Whoogle. Instead, publish the search UI through HTTPS with measured rate limits, point the chosen DNS name at the platform route and proxy only to port 5000.

Exercise this action from outside the host: submit searches with normal and privacy settings, verify result links, test an upstream proxy and trigger the chosen rate limit. If ingress fails, the 502 troubleshooting guide covers port and listener mistakes. If Whoogle receives the request but the upstream blocks the IP or proxy environment variables are incorrect, the evidence now points beyond the proxy.

Make Whoogle startup reproducible

The first container should be easy to delete and recreate. Keep data off the writable layer, bind port 5000 only where the proxy can reach it and pass configuration at runtime.

docker run -d \
  --name whoogle \
  --restart unless-stopped \
  -p 127.0.0.1:5000:5000 \
  -v whoogle-data:/config \
  -e WHOOGLE_CONFIG_PASSWORD=replace-with-a-long-random-value \
  benbusby/whoogle-search:latest

Pin the image after the initial test. Read the earliest startup error rather than the final restart message, verify each mount with docker inspect, and follow logs while you submit searches with normal and privacy settings, verify result links, test an upstream proxy and trigger the chosen rate limit. That sequence distinguishes a bad image command from a dependency or permission problem.

Logs that answer the next question

For Whoogle, monitor a transaction rather than a process: submit searches with normal and privacy settings, verify result links, test an upstream proxy and trigger the chosen rate limit. Combine its latency and error rate with upstream search blocking, server IP reputation, concurrent queries and proxy latency so an alert identifies the constrained component.

The upgrade rehearsal must cover that upstream markup and Whoogle releases can break parsing without making the container unhealthy. Restore, migrate and run the transaction before production replacement. If the upstream blocks the IP or proxy environment variables are incorrect, do not erase data to make startup green; compare version, variables, mounts and dependency reachability in that order.

Turn the Whoogle smoke test into a release check

Create a small, disposable Whoogle fixture and keep it for every release. The fixture should exercise the real workflow: submit searches with normal and privacy settings, verify result links, test an upstream proxy and trigger the chosen rate limit. Record the image digest, external hostname, dependency address and the expected result so a later operator can repeat the test without interpreting this guide.

Run the fixture three times. First, use the fresh deployment. Second, replace the container without touching durable state. Third, restore the backup into an empty environment. The third run passes only when configuration and preferences return and a fixed set of queries still yields usable result links. During each run, capture latency and resource use around upstream search blocking, server IP reputation, concurrent queries and proxy latency; this becomes the baseline for alerts rather than an arbitrary CPU percentage.

Finally, test the negative path deliberately: temporarily deny the test path used by outbound HTTPS access and a stable server IP that search providers accept. Confirm that Whoogle fails visibly without corrupting state, restore the correct condition and repeat the successful transaction. A release record containing those four outcomes is stronger evidence than screenshots of a dashboard or a one-time curl response.

Find every durable byte in Whoogle

Inventory every durable artifact: configuration and any user preferences stored on disk. Mount /config before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. Include configuration that changes how stored data is interpreted, not only the largest directory.

Set retention, copy backups off-host and run a clean-room restore. The Whoogle drill is complete when configuration and preferences return and a fixed set of queries still yields usable result links. If snapshots are part of the plan, use PITR versus snapshot guidance to document what each mechanism can recover.

Protect the valuable part of Whoogle

A secure Whoogle deployment starts by removing authority. Avoid running an open public proxy with no abuse controls; instead, protect any public instance with authentication or rate controls and keep proxy credentials out of the image.

Replace the sample WHOOGLE_CONFIG_PASSWORD immediately, store it outside the image and rotate it like an administrator credential if it is exposed. Restrict administrative routes, use private DNS for dependencies and review every bind mount. When logs are shipped centrally, filter secrets and private content before they leave the server.

What Dockup should automate for Whoogle

Dockup removes manual reverse-proxy and lifecycle work around Whoogle. The service receives a stable HTTPS route to 5000, injected configuration and persistent storage during replacements. An attached customer server follows the same model as Dockup-hosted compute.

After launch, satisfy the application contract: publish the search UI through HTTPS with measured rate limits, allow and verify outbound HTTPS access and a stable server IP that search providers accept and run this proof: submit searches with normal and privacy settings, verify result links, test an upstream proxy and trigger the chosen rate limit. This keeps the one-click experience useful without flattening the details that make Whoogle recoverable and secure.

Frequently asked questions

What does Whoogle need for a production deployment?

Route the Whoogle container on port 5000 through one HTTPS origin. The external delivery requirement is outbound HTTPS access and a stable server IP that search providers accept. Do not call Whoogle ready until you can submit searches with normal and privacy settings, verify result links, test an upstream proxy and trigger the chosen rate limit.

Which Whoogle data belongs in a backup?

Persist /config and include configuration and any user preferences stored on disk in the same recovery manifest. A clean Whoogle restore passes only when configuration and preferences return and a fixed set of queries still yields usable result links.

Does Whoogle require HTTPS behind a reverse proxy?

Use HTTPS for the public Whoogle origin and keep port 5000 on the internal route. Apply the Whoogle setting correctly: publish the search UI through HTTPS with measured rate limits. For Whoogle, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Whoogle upgrade be tested?

Restore current Whoogle state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because upstream markup and Whoogle releases can break parsing without making the container unhealthy. Keep the previous Whoogle image until its data-migration and rollback boundary are understood.