Set up Hubble on EC2 with CloudFormation

README.md

Set up Hubble on EC2 with CloudFormation

Instructions

1. Create new stack with one click or use the provided stack.yaml template (Use a Goerli eth endpoint and leave all other configurations default)
2. Connect to your EC2 instance
   1. Go to the resources tab
   2. Select your EC2 instance
   3. Go to your EC2 instance's primary page
   4. In the top right, select Connect and connect using EC2 Instance Connect with user hubble
3. Run pm2 l and verify that your hubble service is running (this may take a few minutes)
4. Test the connection
   1. Clone hubble locally
   2. Run yarn build
   3. cd into apps/hubble
   4. Run yarn console -s PUBLIC_IP:13112 where PUBLIC_IP is your public IP listed in the CloudFormation outputs tab
   5. You should see a message like Connected Info: {"value":{"version":"1.0.5","isSynced":true,"nickname":"Farcaster Hub","rootHash":""}}

FAQ

How do I access the SSH key?

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html#create-key-pair-cloudformation

How do I view my hub logs?

When you are SSH'd into your EC2 instance under the hubble user, run pm2 logs

pm2 l is not showing my service... what happened?

To further troubleshoot, follow these steps:

1. Connect to your EC2 instance as ubuntu
2. Run su -sh to switch to root
3. Investigate the syslogs (tail -f /var/log/syslog or less /var/log/syslog)

Logs prefaced with cloud-init are associated with the starup script. This is where you will find relevant errors.

stack.yaml

Parameters:
  EthRpcUrlParameter:
    Type: String

Mappings:
  RegionToAmi:  # https://cloud-images.ubuntu.com/locator/ec2/ (Jammy Jellyfish, 22.04 LTS, amd64, hvm:ebs-ssd, hvm)
    sa-east-1:
      AMI: ami-09d1da851644cd52f
    ap-east-1:
      AMI: ami-0f4ab4f13f3b9401b
    us-west-1:
      AMI: ami-0762f1d7b8fd82833
    eu-central-1:
      AMI: ami-050096f31d010b533
    us-east-1:
      AMI: ami-0fd2c44049dd805b8
    af-south-1:
      AMI: ami-0502013bf0f0b5012
    eu-south-1:
      AMI: ami-0fedfdb58a837c2fe
    me-south-1:
      AMI: ami-02c6f8935eb889e98
    ca-central-1:
      AMI: ami-0f6d54280d9fa2b0c
    cn-north-1:
      AMI: ami-05739266c542f05d5
    eu-west-1:
      AMI: ami-0f9ae27ecf629cbe3
    eu-north-1:
      AMI: ami-0b13cbe982c367b75
    ap-south-1:
      AMI: ami-0912cd2fb490de15d
    cn-northwest-1:
      AMI: ami-04c77a27ae5156100
    me-central-1:
      AMI: ami-04be4fee4051bf815
    ap-southeast-1:
      AMI: ami-0434196a03595d088
    ap-northeast-1:
      AMI: ami-00fc5946ba8411dd2

Resources:
  HubbleSecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: Open SSH and Farcaster inbound ports for all clients
      SecurityGroupIngress:
      - IpProtocol: tcp
        FromPort: 22
        ToPort: 22
        CidrIp: 0.0.0.0/0
      - IpProtocol: tcp
        FromPort: 2282
        ToPort: 2282
        CidrIp: 0.0.0.0/0
      - IpProtocol: tcp
        FromPort: 2283
        ToPort: 2283
        CidrIp: 0.0.0.0/0
  HubbleKeyPair:
    Type: AWS::EC2::KeyPair
    Properties:
      KeyName: HubbleKeyPair
  HubbleEc2Instance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !FindInMap [RegionToAmi, !Ref "AWS::Region", AMI]
      InstanceType: m5.large
      SecurityGroupIds:
      - !GetAtt HubbleSecurityGroup.GroupId
      KeyName:
        Ref: HubbleKeyPair
      BlockDeviceMappings:
      - DeviceName: "/dev/sdm"
        Ebs:
          VolumeType: gp3
          DeleteOnTermination: 'false'
          VolumeSize: '20'
      UserData:
        Fn::Base64: 
          !Sub |
            #!/bin/bash

            # General
            apt -y update
            apt -y install jq tmux git

            # Hubble User
            useradd -m -s /bin/bash hubble
            chown hubble:hubble /home/hubble

            # Hub Dependencies and Startup
            sudo -u hubble bash -c '
            # Node Dependencies
            curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
            export NVM_DIR="$HOME/.nvm"
            [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
            source $HOME/.nvm/nvm.sh
            nvm install 18.7.0
            npm install -g yarn pm2

            # Hubble Setup
            git clone https://github.com/farcasterxyz/hubble.git $HOME/hubble
            cd $HOME/hubble && yarn install && yarn build
            cd $HOME/hubble/apps/hubble/ && yarn identity create
            yarn install

            # Start Hub
            export ETH_RPC_URL=${EthRpcUrlParameter}
            pm2 start "yarn start -e $ETH_RPC_URL -b \"/dns/testnet1.farcaster.xyz/tcp/2282\" -n 2" --name hubble'

Outputs:
  PublicIp:
    Value: !GetAtt HubbleEc2Instance.PublicIp
    Description: Public IP of Farcaster hub.