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.
note
We recommend using Visual Studio Code to manage your files.
Install the portal
- Create a repository based on the template repository .
The template includes a follow-along tutorial for you to familiarize with the features and functionality.
- 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.
Warning
Changing package resolutions may cause unexpected behavior in your portal.
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.