Skip to content
Contact us
  • There are no suggestions because the search field is empty.

How do I integrate Prerender.io using the Docker middleware?

Run the official prerender-docker-middleware container as a standalone proxy that routes AI crawlers and search engines to Prerender.io and human visitors to your origin.

TL;DR

The Docker integration is a standalone container that sits in front of your website, inspects the User-Agent on every incoming request, and routes AI crawlers and search engines (Googlebot, GPTBot, ClaudeBot, Perplexity, and others) to Prerender.io while sending human visitors to your origin. You assign a secondary domain to your origin, edit the Dockerfile with your domains and Prerender.io token, deploy the container to your cloud of choice, and re-point your primary domain to the container. Use it when other integrations are not an option for your stack.

 

When to use this integration

The Docker integration is the right choice when:

  • You can't use a Prerender.io integration for a specific server, framework, or CDN.
  • You want a stack-independent component you can drop in front of any origin.
  • You already deploy services as containers and prefer to add Prerender.io the same way.

The integration is published as an official repo at github.com/prerender/prerender-docker-middleware. It uses Nginx inside the container to do the User-Agent split.

 

How it works

The container acts as a reverse proxy. Every incoming request is inspected, and based on the User-Agent header:

  • If the request looks like a known AI crawler or search engine bot, the container forwards it to service.prerender.io with your Prerender.io token attached. Prerender.io returns the cached HTML snapshot of the requested page.
  • If the request looks like a human visitor, the container forwards it to your origin (the secondary domain you set up in Step 1) unchanged.

The DNS dance is the key part: at the end of setup, your primary domain (e.g. www.example.com) points to the container, and the container forwards bot-free traffic to a secondary domain (e.g. www2.example.com) that resolves directly to your origin.

 

How to set up the Docker integration

Step 1: assign a secondary domain to your origin.

Create a secondary domain that points directly to your website. For example, if your primary domain is www.example.com, add a record so www2.example.com also resolves to your origin.

📝 Important: do not add the secondary domain as a CNAME for your primary domain. At the end of this setup you will re-point the primary domain to the Docker container, and if the secondary depends on the primary, you will break the route the container needs to forward human traffic to. Use an A or AAAA record, or a CNAME provided by your hosting provider that does not reference your primary domain.

Step 2: edit the Dockerfile to match your settings.

Clone the prerender-docker-middleware repo and edit the Dockerfile to set your secondary domain, primary domain, and Prerender.io API key. You can find your token under the Security and Access menu in your Prerender.io dashboard.

Environment variables are supported, but for your first setup we recommend hard-coding these values in the Dockerfile so you can rule out environment-configuration issues if something does not work.

Step 3: test the container locally (optional).

If you have Docker Engine or Docker Desktop running on your machine, you can verify the build before deploying:

make run
curl http://localhost:8080

You should see a response back from the container on port 8080. If the build fails or the curl times out, fix the Dockerfile before moving on.

Step 4: deploy the container as a standalone server.

Where you deploy depends on your infrastructure. Common targets include:

Step 5: re-point your primary domain to the container.

Once the container is live, update your DNS so your primary domain points to it. A CNAME is fine here because the container is a brand new component, not your origin.

Step 6: verify with bot and non-bot requests.

Send a couple of curl requests to your primary domain and confirm both routes work.

Normal visitor (forwarded to origin):

curl -A Chrome https://www.example.com

Bot visitor (forwarded to Prerender.io):

curl -A Googlebot https://www.example.com

For the bot request, look for the x-prerender-requestid response header. If it is present, the container correctly routed the request to Prerender.io.

→ For a fuller verification flow including AI crawler User-Agents and the Prerender.io dashboard CDN Analytics check, see how to verify your Prerender.io integration.

✅ Your Docker integration is working when the Googlebot curl returns an x-prerender-requestid response header, the Chrome curl returns your origin's normal HTML, and new entries appear under CDN Analytics in your Prerender.io dashboard within a few minutes.

Optional: secure the secondary domain

💡 You can put your secondary domain behind basic authentication so it never gets crawled or indexed by accident. If you do this, update the Nginx config inside the container to send the matching authentication credentials with each forwarded request. This is optional, but it removes a small risk of the secondary domain being discovered and indexed independently of the primary.

 

Related articles

 

💬 Still need help?
If the container deploys but the integration is not detected, or you are not sure whether your DNS configuration is right, our support team can help.
→ Contact us at support@prerender.io

 

Was this article helpful?