Deploy your doc site to production
Most Consensys documentation sites use Vercel as a hosting platform.
The main benefits of using Vercel instead GitHub Pages for hosting include:
- The ease of integration with GitHub repositories.
- The ability to deploy automatic previews on pull requests.
You can deploy your documentation site in a public GitHub repository or private GitHub repository to production using Vercel. Private repositories require a little more setup.
Public repository
Follow these steps to deploy your public GitHub repository to Vercel:
-
Copy the
vercel.json
file in the root of this template repository to the root of your documentation repository.noteThis file contains some URL redirects from older MkDocs docs before we migrated most Consensys docs to Docusaurus. If your docs did not pre-exist in MkDocs, then you can remove these fields.
importantMake sure
cleanUrls
is set totrue
invercel.json
. This ensures that Vercel deploys the app properly without expecting trailing slashes. -
Determine the public URL that you want to use to expose the doc site. Typically, the URL follows the format of
https://docs.<YOUR_PRODUCT>.consensys.net
. You can customize this to your needs. -
Join the #documentation channel on Consensys Slack and ask for Vercel integration for your repository. Provide a link to your repository in your message.
Once your repository is integrated with Vercel, any new PRs should have a Vercel bot update with a preview link on all new commits to that PR.
Private repository
Follow these steps to deploy your private GitHub repository to Vercel:
-
Join the #documentation channel on Consensys Slack and ask for Vercel integration for your private repository. Provide a link to your repository in your message.
-
Your
build.yml
file in the.github/workflows
directory will be modified to look like the following (you do not need to take this action yourself). Essentially, this modification bypasses Vercel limitations on private repositories by having GitHub actions build and push the static build directly to Vercel..github/workflows/build.yml---
name: Build and Preview
on:
pull_request:
branches:
- main
push:
branches:
- main
jobs:
build:
name: Build
runs-on: ubuntu-latest
# the environment to deploy to / use secrets from
environment: vercel
# modify the default permissions of the GITHUB_TOKEN, to only allow least privileges
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v3
- name: Build
uses: consensys/docs-gha/build@main
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: cp vercel.json ./build
- uses: amondnet/vercel-action@v25.1.1
id: vercel-action-staging
if: github.event_name == 'pull_request'
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.ORG_ID }}
vercel-project-id: ${{ secrets.PROJECT_ID }}
working-directory: ./build
scope: infura-web
- uses: amondnet/vercel-action@v25.1.1
id: vercel-action-production
if: github.event_name == 'push'
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.ORG_ID }}
vercel-project-id: ${{ secrets.PROJECT_ID }}
working-directory: ./build
vercel-args: "--prod "
scope: infura-web
github-comment: falseThe action also provides preview URLs on new commits to a PR.
Set up a private repository with Vercel (for doc team only)
-
Install the Vercel CLI.
-
Run
vercel login
. Make sure you log in with an account that's part of the Infura Web team account. -
Run
vercel link
in the root directory of your Docusaurus project.- Make sure to link to the Infura Web account and not your personal one.
- If you previously created the project in the account, you can link to the existing one. Otherwise, create a new one.
-
After completing the prompts, you should see a
.vercel
directory that includes a JSON file withProject ID
andOrg ID
. -
Log in to the Vercel dashboard and navigate to the Tokens setting.
-
Create a new token with the scope selected to Infura Web and expiration set to never. Make sure to copy this somewhere securely (preferably 1Password), since this token will never be shown again. If you lose it, it must be deleted and regenerated. There's also a security concern, since these tokens have access to the entire Infura Web account.
-
Navigate to your environments setting in GitHub:
https://github.com/consensys/<DOC_REPO>/settings/environments
. -
Create a new environment titled
vercel
. -
Add three new environment secrets to the
vercel
environment:ORG_ID
-orgId
inproject.json
in the.vercel
directory.PROJECT_ID
-projectId
inproject.json
in the.vercel
directory.VERCEL_TOKEN
- Token generated from steps 5-6.
-
Copy the modified
build.yml
file and put it into the.github/workflows
directory. -
Navigate to your project settings on the Vercel dashboard and change the Build & Development Settings under General for Framework Preset to Other and toggle the Override for Build Command and leave it empty. Save these settings.
Any new PR or push to
main
automatically triggers the action to build within GitHub and push the artifacts to Vercel directly. -
Edit the actions if there's something different about your doc repository (for example, the main branch is called
master
instead ofmain
).