@salesforcedocs/portal
Base Package to define a portal that aggregates Writer Asset Repositories into a Site.
While Writer Asset Repositories can also be standalone sites, they are not capable of orchestrating several repositories into a portal.
Portal Start
When the portal starts, these tasks are performed:
- Read the configuration of the site
- Resolve the list of doc repositories ( writer asset repos ), through fetching or linking
- Dynamically generate routes for repo content
- Start the LWR server
Portal Local Repository Linking
The portal has the ability to 'link' an external repository URL with a repository folder on the local file system, which would then configure the build step to read from the local repository folder and not be downloaded from the given github URL. This 'link' step would need to be run before calling portal.start()
.
This is done by performing the linking cli command for each local repository prior to starting the portal.
For example, to link the github repo https://github.com/salesforcedocs/example
to a local clone of the repository under /home/user/example
, run:
sfdocs portal . --link-repo=https://github.com/salesforcedocs/example --link-dir=/home/user/example
Github Authentication
Access to private writer asset repositories in Github is done using Github Apps authentication.
Credentials may be supplied on the local development environment as files under the credentials
folder or through environement variables.
Local dev
When developing locally, you'll want the build to use the certificates directory on the file system vs the environment variables.
If you do not have the environment variables GITHUB_APP_ID
and GITHUB_CERTIFICATE_PATH
specified then it'll use the local file system directory specified in the configuration.certificatesDir
property.
Alternatively, you could specify LOCAL_DEV=1
as an environment variable to toggle local mode.
config.certificatesDir
- The location of certificates on the local file system to use for authentication. Used only when specfied for running local development.
To setup credential files for local development check out this readme
Supply credentials through ENV
Supply these environment variables when running the app:
GITHUB_APP_ID=<ID of your Github App>
GITHUB_CERTIFICATE_BASE64=<Certificate plaintext encoded in base64>
You may also create a .env
file with these variables and specifying the env file in a VSCode VSCode launch command:
{
"configurations": [
...
{
...
"type": "node",
"envFile": "${workspaceFolder}/.env"
}
]
}