Reference UI Deployment Guide (GitHub Pages)

If you've deployed the Council contracts on the blockchain, and are looking for a UI to interact with them, the Council Kit provides a Reference UI that you can deploy and plug into your contracts. You can also follow the video tutorial.

This guide will show you how to deploy the Reference UI on GitHub Pages, but you can use a similar process to deploy it onto your preferred platform instead

Requirements

• A previous deployment of the Council Contracts on the blockchain (follow the deployment guide if you need help)
• GitHub account
• Node provider (e.g. Alchemy)
• More?

Fork the repository

If you already made a fork of the repository to deploy the contracts, you can use that fork. Otherwise, visit the Council Kit repository page on GitHub and use the buttons on the top-right section to make your own fork.

You'll be prompted for a repository name. Keep in mind that this name will become the base path on the URL for this deployment.

Configure GitHub for UI deployment

The Council Kit codebase includes some GitHub Workflows to facilitate deployment in GitHub Pages. You can find these in the path .github/workflows, although you won't need to modify them for this guide.

One of these workflows is used to Deploy the web app to GitHub Pages every time there's a new push to the main branch. To use it, you'll need to follow a few steps on GitHub.

Set GitHub Pages to build from Actions

Go to your repository's Settings tab. Once there, click on the Pages section, and under Build and Deployment, set the Source to GitHub Actions (beta)

Add your environment variables

GitHub Pages will automatically set your page's path to be the name of your repository, so we need to inform the code what that name is. We'll do that by adding a Secret to the repository, which is just a variable. We'll need two:

COUNCIL_UI_BASE_PATH: The base path that GitHub Pages assigns to your deployment. This is our way of letting the app know about it. GOERLI_ALCHEMY_KEY: The code uses Alchemy as its default node provider. We'll go over how to use a different one later on.

Once there, set the new Secret's name to COUNCIL_UI_BASE_PATH, and its value to /<your-repo-name>. Don't forget the forward slash (/).

Use the same process to add your Alchemy API Key with the name GOERLI_ALCHEMY_KEY.

Deploy the council-ui app to GitHub Pages

Now that all our variables and configurations are set, we're ready to do the actual deployment. On the repository page, go to the Actions tab. It will ask for your consent to run Workflows. Once you accept, Look on the left side menu for the Deploy Council UI to GH Pages option.

This workflow is set to run after any changes are pushed to the main branch, but for this first time, we'll run it manually. Look on the right side for the Run workflow dropdown, and click the Run workflow button.

After a few seconds, the screen will update and show that the workflow has started running. It will take a few minutes. What's happening in the background is that the project is getting built with Next.js and uploaded as a static site onto GitHub Pages. You can check more details and even modify the workflow in the .github/workflows/gh-pages-council.yml file.

Once it's finished running, you can click into the workflow task, where you'll find a link to your newly-deployed page under the deploy subtask.

NOTE The contracts that the deployed UI will plug into are gathered in the packages/council-deploy/src/deployments/goerli.deployments.json apps/council-ui/src/

Customization: How to use a different node provider

This guide used Alchemy as the node provider for on-chain data, but you can use any other node provider by making a few adjustments:

• Add the required environment variables on GitHub

If your chosen node provider requires an API key or other environment data, you must add it to GitHub Pages in the same way we added the base path and the Alchemy API key: go to Settings > Secrets and variables > Add Secret and input the Secret's name and value.

• Adjust the Deploy workflow so it reads the newly added variable

You must let the deploy workflow know about the new variables, which you can do by adding them to the file .github/workflows/gh-pages-council.yml.

Look for the following lines:

- name: Build with Next.js
  env:
    NEXT_PUBLIC_MAINNET_ALCHEMY_KEY: ${{ secrets.MAINNET_ALCHEMY_KEY }}
    NEXT_PUBLIC_GOERLI_ALCHEMY_KEY: ${{ secrets.GOERLI_ALCHEMY_KEY }}
    NEXT_PUBLIC_COUNCIL_UI_BASE_PATH: ${{ secrets.COUNCIL_UI_BASE_PATH }}

That's where and how you would add the new Secret you've created on GitHub Pages.

• Add the node provider to the configuration in apps/council-ui/src/providers.ts

You can follow the same template on the apps/council-ui/src/providers.ts file to replace Alchemy for your preferred node provider.