Embedding the developer portal into an existing website's subdirectory

warning

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

You can use one of these three hosted deployment options for our developer portal. Enterprises can also deploy it on-premise, but that is out of scope for this topic.

  1. Whole website - The entire website is built on our developer portal software and hosted by Redocly. For example, https://www.rebilly.com.
  2. Subdomain website- The developer portal exists on its own subdomain. For example, https://developers.willowinc.com/.
  3. Subdirectory website. The embedded developer portal is displayed within an existing website you are happy with or do not have the time/resources to port your content to the developer portal. While many organizations may link to a separate subdomain, you can also adopt a more seamless approach which makes the portal appear as if it is part of the website at a subdirectory.

This guide describes how to embed the developer portal into an existing website's subdirectory.

How the proxy request works

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 use https://example.com/docs/ as the path we want the developer portal to be displayed to the users. For the purposes of this guide, our Redocly project URL is https://example-docs.redoc.ly.

Configuration in Redocly

attention

Ensure that your content in the developer portal repository is at the root path of your repository. The root folder is treated as if it was the /docs path.

In your sidebars.yaml and siteConfig.yaml, you must define relative paths to the files (e.g. ./docs/my-file.md and not /docs/my-file.md).

Your Developer portal content will not function correctly if you try to access the Redocly project URL directly (it will only work properly via the proxy).

Set up the custom domain

  1. In the Redocly app, open the Developer portal you want to embed and select Settings.
  2. From the left, select General and under Custom domain, fill in your custom domain and include the subdirectory path. You should enter the full path that you wish to proxy to (for example, www.example.com/docs).

custom domain dev portal

If you are using a proxy, do not change the CName details.

Configure your proxy

The following section shows how to configure a proxy using these services:

  • nginx
  • Netlify
  • AWS API Gateway
  • AWS CloudFront

nginx

Add the following code to your nginx configuration file.

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, create and save a plain text file named _redirects to your Netlify site's publish directory.

You can add the following rewrite rule in the _redirects file for letting parts of your Netlify site proxy to your Redocly developer portal.

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

All requests to /docs/... proxy through to https://example-docs.redoc.ly straight from Netlify's CDN servers without an additional connection from the browser.

Note: You cannot access proxied URLs during local development.

AWS API Gateway

To configure AWS API Gateway:

  1. Navigate to your gateway resources page and under Actions, select Create Resource. AWS API gateway proxy setup
  2. On the Child Resource page, enter docs in the Resource Name field, at the resource path /docs, and select Create Resource. AWS API gateway proxy setup
  3. Select the docs resource and create a child resource for it. AWS API gateway proxy setup
  4. On the New Child Resource page:

    • Check the proxy resource option.
    • Enter proxy as the resource name.
    • In the Resource path, add {proxy+}. This catches all requests to its sub-resources, which is required for the developer portal. AWS API gateway proxy setup
  5. Once you have created the child resource, navigate to the /docs/{proxy+}-ANY-Setuppage.
  6. Under Integration type, select HTTP Proxy, and add the Redocly project URL https://example-docs.redoc.ly/{proxy} (with the {proxy} at the end). Ensure the content handling is set to Passthrough. AWS API gateway proxy setup
  7. Save your changes.
  8. Select the /docs resource, and from the Actions menu, select Create Method. AWS API gateway proxy setup
  9. On the /docs-ANY-Setup page,

    • Select the integration type as HTTP,
    • Add 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
  10. Save your changes.

::: warning

Re-deploy your gateway for these changes to take effect, before you use it with Redocly.

:::

AWS CloudFront

To configure AWS CloudFront:

  1. On the CloudFront Distributions page, select Create Distribution. AWS CloudFront setup The Select a delivery method for our content page displays.
  2. On the Select a delivery method for your content page, select Get Started. The Create Distribution page displays.
  3. Under Origin Settings, complete the following:

    • In the Origin Domain Name, enter example.com.
    • From Origin Protocol Policy, select HTTPS Only.
  4. Under Default Cache Behaviour Settings, select the following:

    • Fromt the Viewer Protocol Policy, select Redirect HTTP to HTTPS.
    • From Allowed HTTP Methods, select GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE. AWS CloudFront setup
  5. Save your changes. The new distribution is added to the CloudFront Distributions page. AWS CloudFront setup
  6. Select to view the Distribution details. On the Distribution details page, from the Behaviors tab, select Create Behavior. AWS CloudFront setup
  7. On the Create Behavior page, complete the following:

    • In the Path Pattern field, enter /docs*
    • From Cache and origin request settings, select Use legacy cache settings.
    • From Object Caching, select Customize.
    • In the Minimum TTL field, enter 86400. AWS CloudFront setup
  8. Save your changes. The CloudFront Distributions page is updated with a CloudFront Domain Name. AWS CloudFront setup
  9. Navigate to Portal settings in Redocly Workflows to add the custom domain details to the Portal. AWS CloudFront setup There are two ways you can do this:

    • On the Change your custom domain dialog, in the Custom domain field, enter the CloudFront Domain name. AWS CloudFront setup
    • On the Change your custom domain dialog, in the Custom domain field, enter example.com/docs. AWS CloudFront setup

Questions

Have questions? Using a different proxy? Contact us.