On-premise reference docs

If you want to deploy Reference docs on-premise due to specific security constraints, you can use one of these ways:

  • Using an HTML element (easiest)
  • Using a CLI tool to build static documentation (medium)

Prerequisites

  1. Web server or CDN (for the HTML page with the HTML element or to host the static files generated by the CLI).
  2. Node v12 or higher (to build static files with the CLI).

Self-hosted routing

If you are hosting Reference docs on your own, you may get a 404 error after refreshing the page or following a link with a sub-path on it. This is expected behavior for Single Page Applications (SPA), because the routing logic is controlled by the client application (your Reference docs), not by the web host.

To work around this issue, you can:

  • set pagination: none in the configuration file for your Reference docs. This disables pagination and displays all content on a single page. Read more about the pagination option in the list of supported configuration options,
  • or create a special "SPA Fallback" configuration that will control the routing. The routing should be configured so that every route receives the same HTML response and runs the client application in the browser. There is no universal way to set up the "SPA Fallback" as it depends on your hosting, so you may need to consult additional external documentation.

Local development server

If you want to run the development server, you may do so with the Starter plan or greater as part of our openapi-cli tool with the preview-docs command (after you login). See more information here:

On-premise license key

To start using Redocly API reference docs on-premise, you need to have a license key. The on-premise functionality is supported only in our Enterprise plans.

  • If you already have an Enterprise account with access to the Workflows app, you can generate the license key for your organization.
  • To request a license key, contact us at team@redoc.ly.

Generating the license key

  1. Log into Workflows, and select Settings. You must have the Owner role at the organization level in the app to access the Settings page.
  2. From the left menu, select On-premise license keys.
  3. On the On-premise licence keys page, select New license key. The Licence key generation dialog displays.

    • If you have previously generated a license key, it is displayed on the page along with its expiration date and the list of allowed domains.
    • If there is no existing key, select the Generate license key button to generate a new one. When (re)generating a key, you can add up to 10 domain names to the allowlist. All subdomains of an added domain are included by default.
  4. On the Licence key generation dialog, type in your domain and click Generate key.

You can add up to 10 domain names for one key. Select Add domains under the active license key to add more domain names.

warning

You cannot edit previously added domains for the currently active license key. To change these domains, you will need to generate a new license key.

Any previously generated keys are listed on the page in the History section. You can remove these keys from the list after they expire by selecting the recycle bin/delete icon next to each key in the list.

About licence keys

Every license key is a base64-encoded string containing information about the expiration date and allowed domains.

To start using the license key you've generated, copy it from the On-premise license keys page and save it for future use. The key does not need to be encrypted and can be stored in a plain text file.

Using the licence keys

After you've obtained the license key, you can start using Redocly API reference docs on-premise in one of the following ways:

To deploy Reference docs using Docker, contact us at team@redoc.ly to see if you have the proper indications for that.

HTML element

When using the HTML element with the JavaScript library from CDN, provide the license key in the options argument of RedoclyReferenceDocs.init call:

Copy
Copied
RedoclyReferenceDocs.init(
  '<path to api definition>',
  {
    licenseKey: '<license-key-here>',
  },
  document.querySelector('#redocly_container'),
);

CLI

There are two ways to provide a license key when using the CLI:

  • Using an environment variable REDOCLY_LICENSE_KEY.
  • Using the .redocly.yaml configuration file.

The @redocly/reference-docs CLI will search for this .redocly.yaml file in the current working directory with the license specified in the following format:

Copy
Copied
referenceDocs:
  licenseKey: '<license-key-here>'

Example to set the license key as an environment variable:

Copy
Copied
REDOCLY_LICENSE_KEY=<license-key-here> reference-docs bundle openapi.yaml