Farcaster Hub

IAC used for managing the deployment of a Farcaster hub within a fresh GCP project

Architecture Overview

• All GCP and Kubernetes resources defined and managed by Terraform
• Persistent disk mounted to the local rocksdb directory
• Static IP and corresponding DNS record provisioned
• Small, dedicated GKE cluster is provisioned within its own dedicated VPC
• Nginx Reverse Proxy Kubernetes LoadBalancer service is provisioned along with corresponding firewall rules for inbound HTTP, RPC and libp2p traffic
• A GCP Artifact Registry instance (optional, and private to the GCP project) is used for the custom prometheus infrastructure
• Kubernetes Secrets are deployed to manage the TLS certificate, Alchemy/Infura/etc node RPC URL and the libp2p peer identity used by the hub
• Graphite and Grafana Stack provided by the Farcaster team monitoring hub status

Copying This Deployment

This configuration is written for a clean GCP project.

Most things should work as-is for running in any GCP project.

You may want to at least:

• Change the DNS records created by terraform
• Update the domain names for Nginx
• Edit the backend where terraform plans and runs (currently using hosted terraform.io)
• Ensure terraform is configured with credentials to a GCP service account with appropriate scopes to create GCP resources (including new IAM roles)
• Edit the per-GCP-project values in vars.tf
• Remove configuration to create the GCP docker repository if it has already been created for the GCP project
• Set the value for the hub libp2p peer ID kubernetes secret
  • Run the docker image locally and generate a new libp2p identity (yarn identity create && base64 -w0 .hub/default_id.protobuf)
  • Upload the base64 value as a new secret value revision
• Set the values for the kubernetes secrets at gke_secrets.tf
• Update the docker repository in docker-bake.hcl used in pushing new build images

Update Instructions

Simple changes to the config of the hub can be propagated as follows:

1. Fetch the tag of the new hub docker image from https://github.com/farcasterxyz/hub-monorepo/releases
2. Write the image tag to kubernetes -> image = "farcasterxyz/hubble:[TAG]"
3. If using terraform cloud, commit and push to the git remote to trigger a deployment at https://app.terraform.io/