Farcaster Notification Bot

Overview

This page provides generic contributor documentation for the Nouns Builder Farcaster bot.

Proposal and Propdate notifications are propagated to the existing Farcaster bot using a CRON job that runs every hour.

Setup Instruction

Step 1: Create a New Repository on GitHub

Go to GitHub and log in to your account.
Click the + icon in the top right corner and select New repository.
Enter a Repository name of your choice—try to make it descriptive and easy to remember.
Leave the repository empty for now:
- Uncheck the box for “Add a README file.”
- Do not add any .gitignore or license files.
Choose whether you want the repository to be public or private depending on your use case.
Click Create repository to finish up.

Step 2: Clone the Repository

In this step, we’re going to clone an existing repository to your local machine.

First, you need to have the GitHub CLI (gh) installed. If you don’t already have it, you can install it from the GitHub CLI documentation. It’s available for all major operating systems, and trust me, it makes interacting with GitHub a lot easier.
Once you have gh installed, use the following command to clone the repository:
Terminal window
```
gh repo clone nouns-build/builder-farcaster
```
This command will clone the nouns-build/builder-farcaster repository into your local development environment. Ensure you run it from the desired directory where you want the repository files to be stored.
After cloning, you should see a new folder named builder-farcaster containing all the files of the repository. You can navigate into this folder to start working on the project.

Step 3: Change Repository Origin and Push to GitHub

Now that you have the repository cloned locally, let’s change the remote repository’s origin to your new GitHub repository and push the changes.

Navigate into the cloned repository:
Terminal window
```
cd builder-farcaster
```
Change the Git remote origin to point to your own repository. Replace <your-github-username> and <your-repo-name> with your GitHub username and the repository name you created in Step 1:
Terminal window
```
git remote set-url origin https://github.com/<your-github-username>/<your-repo-name>.git
```
Verify that the new origin URL is set correctly:
Terminal window
```
git remote -v
```
You should see the updated URL pointing to your GitHub repository.
Push the changes to your GitHub repository:
Terminal window
```
git push -u origin master
```
This command will push the local content to your newly created GitHub repository, making it available online for collaboration or deployment.

Step 4: Set Environment Variables and Secrets

You can configure the environment variables and secrets either through the GitHub CLI as described below or directly from your GitHub repository settings page, under the ‘Settings’ tab, by navigating to ‘Secrets and variables’. These configurations are essential for setting up the deployment and running the application in different environments.

Next, we will configure the environment variables and secrets for the repository using the GitHub CLI.

Set the environment variables using gh:

gh variable set NODE_ENV --body "production"
gh variable set DATABASE_URL --body "file:./prod.db"
gh variable set BUILDER_SUBGRAPH_ETHEREUM_URL --body "https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-ethereum-mainnet/stable/gn"
gh variable set BUILDER_SUBGRAPH_BASE_URL --body "https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-base-mainnet/stable/gn"
gh variable set BUILDER_SUBGRAPH_OPTIMISM_URL --body "https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-optimism-mainnet/stable/gn"
gh variable set BUILDER_SUBGRAPH_ZORA_URL --body "https://api.goldsky.com/api/public/project_clkk1ucdyf6ak38svcatie9tf/subgraphs/nouns-builder-zora-mainnet/stable/gn"
gh variable set WARPCAST_BASE_URL --body "https://api.warpcast.com"

Set the secrets using gh for sensitive information (Note: Secrets for Builder projects are available in the shared vault:
- WARPCAST_API_KEY can be found under Builder Bot Farcaster > Direct Cast API Key
  - If you are using this setup for personal purposes, you can obtain your API KEY by following the instructions here: Public Programmable DCs v1)
- WARPCAST_AUTH_TOKEN can be found under Builder Bot Farcaster > Warpcast Authentication Token
Terminal window
```
gh secret set WARPCAST_API_KEY
gh secret set WARPCAST_AUTH_TOKEN
```
- A base64-encoded SSH_PRIVATE_KEY can be found under Builder Farcaster Droplet (Deploy) > Private Key
  - to decode it, copy the text and run pbpaste | base64 -d in your local terminal (don’t use online tools for this)
  - sicne it’s multiline, you can create a file called tmp and put the contents in there (including -----BEGIN OPENSSH PRIVATE KEY----- and -----END OPENSSH PRIVATE KEY-----
Terminal window
```
gh secret set SSH_PRIVATE_KEY --body @tmp
rm tmp
```
These commands will securely add environment variables and secrets to your GitHub repository. Properly setting these variables ensures your project has the right configuration to connect to the necessary services and environments.

Deployment Instructions

Branching and Versioning Strategy

In this repository, we keep ongoing changes on the develop branch, which acts as our main integration branch. When changes are ready for production, we merge them into the master branch. Each merge to master is accompanied by a proper SemVer tag, and the version number is updated in the package file accordingly.

Each time changes are pushed to the master branch under these conditions, a new GitHub release is generated. When you publish a GitHub release, it triggers another workflow that builds the project and pushes it to the deployment server using the secrets and variables provided during setup.

In this repository, we use a combination of Git Flow and GitHub Flow to manage our branching strategy. Git Flow helps us structure our development process by using feature branches and releases, while GitHub Flow allows for a simplified workflow for quick changes and collaboration.

For versioning, we follow Semantic Versioning (SemVer), which means version numbers follow the pattern MAJOR.MINOR.PATCH and increment based on backward-incompatible changes, new features, and bug fixes, respectively.

By following these practices, we ensure a structured approach to development, testing, and releasing new versions of the software, which helps in maintaining quality and reliability throughout the project lifecycle.

Step 1: Set Environment Variables

The following environment variables are set on GitHub for deployment purposes, based on the deployment server configuration. Use the gh command to set them:

gh variable set REMOTE_HOST_NAME --body "68.183.109.99"
gh variable set REMOTE_HOST_NODE --body "/usr/bin/node"
gh variable set REMOTE_HOST_PATH --body "/home/deploy/builder-farcaster"
gh variable set REMOTE_HOST_PNPM --body "/usr/local/bin/pnpm"
gh variable set REMOTE_HOST_USER --body "deploy"

Ensure these variables are configured correctly in the repository settings to guarantee smooth deployment.

Step 2: Branching Strategy

Create a Feature Branch: Start by creating a feature branch from the develop branch. Use a descriptive branch name to make it easy to understand its purpose:
Terminal window
```
git checkout -b feature/<feature-name>
```
This ensures that ongoing changes are isolated and do not interfere with the main codebase until they are ready to be merged.
Merge Changes into Develop: Once your feature or bug fix is complete and reviewed, merge it back into the develop branch:
Terminal window
```
git checkout develop
git merge feature/<feature-name>
```
The develop branch serves as the main integration branch where all ongoing development work is consolidated.
Prepare for Release: When the changes are ready for production, create a release branch from develop:
Terminal window
```
git checkout -b release/<version-number>
```
Release branches are meant for final preparation of a release, including testing and minor adjustments.
Update Version in Package File: Update the version number in the package.json or equivalent package file before merging. This ensures consistency between the tagged version and the project metadata.
Merge into Master: After testing, merge the release branch into the master branch:
Terminal window
```
git checkout master
git merge release/<version-number>
```
The master branch is the production-ready branch and should always reflect the latest stable version of the code.
Tag the Release: Tag the new version in line with Semantic Versioning (SemVer):
Terminal window
```
git tag -a v<version-number> -m "Release version <version-number>"
git push origin v<version-number>
```
Tagging helps in keeping track of different versions of the project and makes it easier to roll back if needed.

Step 3: GitHub Release

Generate Release: Push the changes to the master branch. A GitHub release will automatically be generated from this push.
Publish the Release: Navigate to the releases page in the GitHub repository, edit the release notes if needed, and click Publish Release. This makes the new version officially available for use and further deployment.

Step 4: Deployment Workflow

Deployment Trigger: Publishing the GitHub release will trigger a deployment workflow. This is an automated process that starts as soon as a new release is published.
Build and Deploy: The workflow will build the project and push it to the deployment server using the secrets and environment variables configured during the setup. The build process uses the environment configurations from the master branch to ensure consistency.

The deployment process makes sure that the latest stable version is available in the production environment, and the environment variables are appropriately set to match the production settings.
Verify Deployment: Once deployed, verify the application is running as expected in the production environment. This may involve running some manual or automated tests to ensure everything is functioning correctly after the deployment.