Install the developer portal

Prerequisites

Before installing the the developer portal:

• Install yarn . It works across all the major operating systems.
• Know how to run the commands from the CLI (for example, yarn install ). For Windows, we recommend using Git Bash .
• Learn common git techniques (creating a branch, committing, and in our examples, opening a pull request on GitHub.)
• Get familiar with Markdown.

Install the portal

1. Create a repository based on the template repository .

The template includes a follow-along tutorial for you to familiarize with the features and functionality.

2. Install the project.

yarn install

Run the development server

yarn start

Preview your files on the local server displayed in the terminal.

Troubleshooting installation

If an error occurs during installation, delete the yarn.lock file, and then try to install it again.

rm yarn.lock
yarn install

If the installation problem persists, please contact us.

Ignore optional dependencies

It's possible to install the portal without optional dependencies. You may want to do this for testing purposes, or if you don't need to use extra options (such as image optimization) in your local development server.

yarn install --ignore-optional

Set up package resolutions

When installing the portal, you may get warning messages in the log about detected vulnerabilities. Similarly, if you are using any security auditing tools or dependency scanning utilities, they may indicate a large amount of vulnerable packages in the portal.

This issue is caused by one of our core dependencies, gatsby, which by default requires a lot of packages, even though many of them are not used at all in the Developer portal. Many of the vulnerabilities reported in those packages are not exploitable, but they still get reported as security issues. To understand why this happens, read more about problems with npm package auditing.

Because Redocly doesn't have control over the majority of those packages, we can't fix the reported vulnerabilities in them directly. Instead, we recommend setting up package resolutions. With this approach, you can override package versions that are reported as problematic.

To set up package resolutions and avoid vulnerability warnings, add the following resolutions section to your package.json file:

"resolutions": {
    "styled-components": "5.3.3",
    "immer": "9.0.12",
    "xmlhttprequest-ssl": "1.6.3",
    "axios": "0.21.4",
    "object-path": "0.11.8",
    "prismjs": "1.26.0",
    "postcss": "8.4.6",
    "css-what": "6.0.1",
    "trim-newlines": "3.0.1",
    "glob-parent": "5.1.2",
    "ws": "7.5.5",
    "dns-packet": "1.3.4",
    "browserslist": "4.19.1",
    "trim": "0.0.3",
    "sanitize-html": "2.7.0",
    "engine.io": "4.1.2",
    "normalize-url": "4.5.1",
    "semver-regex": "3.1.3",
    "path-parse": "1.0.7",
    "ansi-regex": "5.0.1",
    "nth-check": "2.0.1",
    "url-parse": "1.5.4",
    "simple-get": "4.0.1",
    "follow-redirects": "1.14.8",
    "marked": "4.0.12",
    "tar": "6.1.9"
}

Redocly will test all recommended resolutions and update this list regularly. Make sure to check this documentation page for updates.

As this is only a short-term solution, we're working on the long-term one. That will include replacing the current Developer portal codebase with a more modern, improved one controlled by Redocly.