Summary

This walkthrough shows how to automate your development process so any change to your node codebase can be automatically built, and then deployed to an existing or new OnFinality network.

  • Integrating OnFinality’s CLI into GitHub actions to:

    • Update Network spec

    • Deploy new nodes

    • Perform a rolling update to existing nodes in network spec

  • Common deployment strategies regarding dev and staging environments

Prerequisites

  • A valid user network and running nodes on OnFinality

  • A existing pipeline that build and publish binary to dockerhub

  • The OnF CLI tool is locally installed and has an access key configured. OnFinality CLI Tool and Access Keys

  • You have access to and generated a chainspec file

Other Resources

Chain Config Files

Chain Config for Standalone Chain/Parachain

We have provided some example chainspec files in at https://github.com/OnFinality-io/onf-cli/tree/master/sample/onf-testnet :

  • bootstrap-parachain-config.yaml (parachain)

networkSpec

  • You can see basic information about the image version, including the node types and the reference to the chain spec file that was created earlier.

  • Also included are links to the bootnodes libp2p address for the parachain

validator

  • In the example files we have configured to automatically deploy 3 validators as part of the bootstrap process. 

  • These three are all in the OnFinality Japan location and have 2 compute units with 30 GB of storage.

  • Each will expose a public port and will be protected via an API key

bootNode

  • If you want to add bootnodes for the new network, you can adjust the count property in the bootNode section. Then all the new created bootnodes libp2p address will be updated to the network spec.

Start Network

Bootstrap Relaychain (Optional)

Skip this step if your chain is not running as a parachain (it’s running as a standalone chain)

run onf network bootstrap -f bootstrap-relaychain-config.yaml

After you run the command, OnFinality will create a new network spec in the workspace and deploy any new nodes as defined in the config file.

Bootstrap Parachain/Standalone Chain.

Firstly, you need to modify --bootnodes parameters in the networkspec definition section to replace with addresses from the bootnodes you created in the previous step. you can get the libp2p address in the OnFinality webapp, or via cli tool.

run onf network bootstrap -f bootstrap-parachain-config.yaml

After you run the command, OnFinality will create a new network spec in the workspace and deploy any new nodes as defined in the config file.

Automate via a GitHub Action (optional)

Assuming there's a workflow that will build and publish the Docker Image to dockerhub like the following:

name: Publish Docker image for new releases

on:
  push:
    branches: [ main ]

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
        
      - name: Login to Dockerhub
        uses: docker/login-action@v1
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
          
      - name: Declare some variables
        id: vars
        shell: bash
        run: |
          echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"
          echo "::set-output name=sha_short::$(git rev-parse --short HEAD)"
          
      - name: Build and push
        id:   docker_build
        uses: docker/build-push-action@v2
        with:
          push: true
          file: scripts/Dockerfile
          tags: |
            onfinality/acala:${{ steps.vars.outputs.sha_short }}
            
      - name: Image digest
        run: echo ${{ steps.docker_build.outputs.digest }}
YAML

Note that the new image version is the first 7 letter of the commit hash (sha_short).

Now we add two steps in the end, the first one will push the new image version to an existing OnFinality Network Spec, the second one will do a rolling upgrade for all nodes to the new version.

      - name: Update image version of the existing network spec
        uses: "OnFinality-io/action-onf-release@v1"
        with:
          # These keys should be in your GitHub secrets
          onf-access-key: "THc4hqtMNPVgLZwXtjO2PJQDkKETFpYA"
          onf-secret-key: "KhD6kp3Y3KejNeP3DH+sMTT4od20oUC0UCB0U6dk"
          onf-workspace-id: "6683212593101979648"
          onf-network-key: b27bcdd4-fee0-44a2-9dae-62006051ef48
          # Add a new image version to network spec
          onf-sub-command: image
          onf-action: add
          image-version: ${{ steps.vars.outputs.sha_short }}

      - name: Perform a rolling upgrade to all nodes
        uses: "OnFinality-io/action-onf-release@v1"
        with:
          # These keys should be in your GitHub secrets
          onf-access-key: "THc4hqtMNPVgLZwXtjO2PJQDkKETFpYA"
          onf-secret-key: "KhD6kp3Y3KejNeP3DH+sMTT4od20oUC0UCB0U6dk"
          onf-workspace-id: "6683212593101979648"
          onf-network-key: b27bcdd4-fee0-44a2-9dae-62006051ef48
          # Perform a rolling ugrade to nodes
          onf-sub-command: node
          onf-action: upgrade
          image-version: ${{ steps.vars.outputs.sha_short }}
          percent: 30 # Percent of nodes to update at each time
YAML

Extend it Further

A lot of possibilities are left to be explored. Once a new version rolled out, you can execute some tests for the new client. And then an extra step to upgrade the runtime to the new version, before running other tests for the new runtime.