Last updated 3 months ago

Embed the developer portal into an existing website

This article applies to the developer portal (not the reference docs).

There are three hosted deployment options for our developer portal (and enterprises may also deploy it on-premise -- out of scope for this article).

  1. Whole website. Example: https://www.rebilly.com (the entire website is built on our developer portal software and hosted by us).
  2. Subdomain website. Example: https://developers.willowinc.com/ (the developer portal exists on its own subdomain).
  3. Embedded website. The embedded website is indicated when you have an existing website you are happy with or don't have the time/resources to port your content to the developer portal. While many will just link to a separate subdomain, it is possible to generate a more seamless approach which makes the portal appear as if it is part of the website.

Proxy request path

1
2
3
4
Browser
Proxy
Redocly
  1. The web browser makes a request to the proxy.
  2. The proxy, in turn, makes a request to Redocly, while keeping the connection open.
  3. Redocly responds to the proxy with content (HTML, CSS, JS, images, etc...).
  4. The proxy forwards that response onward to the web browser.

Throughout this guide, we'll use https://example.com/docs/ as the path we desire the developer portal to be displayed to users.

Let's say our Redocly project URL is https://example-docs.redoc.ly.

Configuration in Redocly

Proxy path setting

Proxy path settings

Before you start, navigate to your developer portal in Redocly.

  1. Switch to the settings tab.
  2. Go to the Advanced tab.
  3. Enter /docs and submit the form to change the prefix.
Your content in the developer portal repository should be at the root path of your repository. This setting treats that folder as-if it was the docs path.

Your sidebars.yaml and siteConfig.yaml should define relative paths to the files (e.g. ./my-file.md and not ./docs/my-file.md).

Also, your content will not function correctly if you try to access the Redocly project URL (it will only work properly via the proxy).

Custom domain setup

Fill in your custom domain.

custom domain dev portal

Because you are using the proxy pattern, you should not change your CNAME record as the screen suggests.

Configure your proxy

This guide shows how to configure a proxy using three examples: nginx, Netlify and AWS API Gateway.

nginx

location /docs/ {
  proxy_ssl_server_name on;
  proxy_pass https://example-docs.redoc.ly/; # trailing slash is important here
}

Netlify

Proxying is part of Netlify's redirects support. To configure redirect and rewrite rules for your Netlify site save a plain text file named _redirects to the publish directory of your Netlify site.

A rewrite rule in the _redirects file for letting parts of your Netlify site proxy to your Redocly developer portal could look like this:

/docs/*  https://example-docs.redoc.ly/:splat 200

Now all requests to /docs/... will be proxied through to https://example-docs.redoc.ly straight from Netlify's CDN servers without an additional connection from the browser.

Keep in mind that proxied URLs won’t be accessible during local development.

AWS API Gateway

Configuration of the AWS API Gateway is more complex than nginx.

First, navigate to your gateway and create a resource. AWS API gateway proxy setup

Then, we create our resource named docs at the resource path /docs.

AWS API gateway proxy setup

Next, we'll select our resource and create a child resource for it. Be sure to check the "proxy resource" option. AWS API gateway proxy setup

Fill the form as pictured with proxy as the resource name and {proxy+} as the value. This will catch all requests to its sub-resources which is required for the developer portal.

AWS API gateway proxy setup

Next, configure it as an HTTP Proxy and paste in your Redocly project URL https://example-docs.redoc.ly/{proxy} (with the {proxy} at the end).

Be sure the content handling is set to passthrough.

AWS API gateway proxy setup

Next, select the /docs resource and then select Create Method from the Actions menu.

AWS API gateway proxy setup

Select the integration type as HTTP, paste your Redocly project URL (https://example-docs.redoc.ly/ in this guide) with a trailing slash, and set content handling to Passthrough.

AWS API gateway proxy setup

You MUST re-deploy your gateway for the changes to take effect.

Questions

Have questions? Using a different proxy? Contact us.