ContextQMD
Back to Handsontable

Documentation deployment guidelines

docs/README-DEPLOYMENT.md

17.0.15.6 KB
Original Source

Documentation deployment guidelines

This page covers guidelines for deploying the Handsontable documentation.

About documentation deployment

A prod-docs/<MAJOR.MINOR> branch with the largest version number gets automatically tagged as the documentation's latest version.

Our server configuration watches for images tagged with :v12.1, :v13.0 and so on, and automatically refreshes after detecting a newer version.

Docker settings

Before generating the documentation, set Docker's runtime memory limit.

The recommended runtime memory limit is 8 GB. It allows us to generate 4 documentation versions at a time.

Deploying the documentation

Handsontable's GitHub Actions setup deploys the documentation based on the following Docker image tags:

Docker image tagBuild typeTriggered byUsed for
:v12.1, v13.0 etc.ProductionA push that changes docs/** on the Docs production branch e.g prod-docs/12.1Automatic production deployment
:v12.1-[COMMIT_HASH], :v13.0-[COMMIT_HASH] etc.ProductionA push that changes docs/** on the Docs production branch e.g prod-docs/12.1Images used for backups

Deploying the documentation to the staging environment

Staging documentation is being deployed on netlify either automatic on manually based on the following diagram.

mermaid
flowchart TD
    Docs[Documentation Stage on Netlify]
    Push[Push on files <pre>docs/*</pre>]
    Manual[Manual <pre>workflow_dispatch</pre>]
    PullRequest[Pull Request event] 
    PullRequestClose[Pull Request close]
    Generate[Generate a preview at <pre>dev-handsontable-BRANCH_NAME.netlify.app</pre>]
    Destory[Destory, if exsist, a preview at <pre>dev-handsontable-BRANCH_NAME.netlify.app</pre>]
    Push -->|Automatic| Generate
    Manual -->|Manual trigger on selected branch| Generate
    PullRequest --> |Manual approve on PR page| Comment[Bot comments on PR page with URL]  --> Generate
    PullRequestClose --> |Automatic| Destory    
    Generate -->|Manual trigger| Destory
    Docs --> Push
    Docs --> Manual
    Docs --> PullRequest
    PullRequest --> PullRequestClose

workflow_dispatch manual trigger on any branch

To deploy the documentation to the staging environment, from GitHub Actions:

  1. Go to github.com/handsontable/handsontable/actions.
  2. Select the Docs Staging Deployment workflow.
  3. Select the Run workflow drop-down.
  4. Select the branch that you want to deploy.
  5. Select Run workflow.

Manual trigger on pull request page

On pull request page there will be pipeline in waiting mode that once approved will (re)generate a staging version of documentation and bot will send url in PR comment.

When pull request is closed staged version will be delegated to destroy.

Manually deploying the documentation to the production environment

To deploy the documentation to the production environment, from GitHub Actions:

  1. Go to github.com/handsontable/handsontable/actions.
  2. Select the Docs Production Deployment workflow.
  3. Select the Run workflow drop-down.
  4. Select the Docs production branch that you want to deploy (e.g docs-prod/12.1).
  5. Select Run workflow.

To deploy the documentation to the production environment, from the command line:

  1. When deploying for the first time, log in to the GitHub Container Registry (ghcr.io):

    bash
    docker login --registry docker.pkg.github.com

  2. Deploy the documentation:

    bash
    npm run docs:docker:build:production

docker push docker.pkg.github.com/handsontable/handsontable/handsontable-documentation:v12.1

Reverting a production deployment

To revert a production deployment to a previous version (on the example of a broken version 12.1):

  1. Pull a previously-deployed Docker image of your choice, tagged with [COMMIT_HASH]:
    bash
    docker pull docker.pkg.github.com/handsontable/handsontable/handsontable-documentation:v12.1-[COMMIT_HASH]
  2. Make the production Docker tag refer to your [COMMIT_HASH] version:
    bash
    docker tag docker.pkg.github.com/handsontable/handsontable/handsontable-documentation:v12.1-[COMMIT_HASH] docker.pkg.github.com/handsontable/handsontable/handsontable-documentation:v12.1
  3. Push the production Docker image (which is your [COMMIT_HASH] version now) back to the registry:
    bash
    docker push docker.pkg.github.com/handsontable/handsontable/handsontable-documentation:v12.1