adam-hanna/TUTORIAL.md

## TUTORIAL.md

      
    Raw
  

              TUTORIAL.md
            
          
    instructions for building & testing dht-tracer

Step 0: read the project brief

Read this project-brief -- it will give you an understanding of what the goals are for this tool.
Step 1: get the right code

We're using code in branches and forks because we're working on top of stabilize dht/libp2p improvements that haven't fully landed, and because we're working w/ AE (working on forks/private repos for now).
I believe the code is the following:

check out workspace-go-libp2p - https://github.com/libp2p/workspace-go-libp2p/
use stabilize branch on any libp2p repo that has it (see A1 section below)
use tracer branch in go-libp2p-kad-dht   from https://github.com/mplaza/go-libp2p-kad-dht/tree/tracer (ie mplaza's repo)
tracer in https://github.com/mplaza/go-todocounter (clone it in the workspace)
master in https://github.com/mplaza/dht-tracer1 (backend) (in the workspace, but get mplaza's code)
master in https://github.com/protocol/dht-tracer-private (frontend) (you'll need to clone this separately)

go-libp2p-kad-dht code

cd workspace-go-libp2p/go-libp2p-kad-dht
git remote add mplaza git@github.com:mplaza/go-libp2p-kad-dht
git fetch mplaza
git checkout mplaza/tracer

dht-tracer1

cd workspace-go-libp2p
git clone git@github.com:mplaza/dht-tracer1

go-libp2p-core

cd workspace-go-libp2p
git clone git@github.com:libp2p/go-libp2p-core
cd go-libp2p-core
git checkout stabilize

go-todocounter

cd workspace-go-libp2p
git clone git@github.com:mplaza/go-todocounter
git checkout tracer

dht-tracer-private (frontend)

cd workspace-go-libp2p
git clone git@github.com:protocol/dht-tracer-private

Step 2: build the backend & test

build backend (https://github.com/mplaza/dht-tracer1/tree/master/tracedht) run it, check you can make cmds with curl as in the examples https://github.com/libp2p/dht-tracer1/blob/master/tracedht/tracedht.go#L51-L69
Get mplaza's changes and go-todocounter (see Step 1. above)
cd workspace-go-libp2p/dht-tracer1/tracedht
go build
Run it
> # open 3 terminal windows
> (term1) ./tracedht --serve :7000
> (term2) curl "http://localhost:7000/events"
> (term3) curl "http://localhost:7000/cmd?q=put-value+/v/foobar+baz"

You can keep issuing commands in term3. tracedht can do a bunch -- see help output in A2 below.
It can also be used against a local network. i made a simple tool to do this (localdht, see A3 below if you're interested, but this is less documented. (obligatory dragon warning)
Step 3: build the frontend & test

build frontend (https://github.com/protocol/dht-tracer-private) and test it out
# clone the code
cd workspace-go-libp2p/dht-tracer-private

# install deps
yarn

# start app
yarn start

This should open your browser and go to http://localhost:3001, where you can see the dht-tracer frontend in action. (see the videos on slack to get a sense of how it works)
CORS workaround

Note: you will need to work around CORS, probably: https://stackoverflow.com/questions/10883211/deadly-cors-when-http-localhost-is-the-origin
echo "127.0.0.1 lvh.me" >>/etc/hosts

Step 4: Profit


Appendix

A1: ./workspace.sh branch output

This is my workspace-go-libp2p/workspace.sh branch output. (see https://github.com/libp2p/workspace-go-libp2p/blob/master/workspace.sh#L108 )
> ./workspace.sh branch
dht-tracer1                   master
go-addr-util                  master
go-buffer-pool                master
go-conn-security-multistream  master
go-eventbus                   master
go-flow-metrics               master
go-libp2p                     stabilize
go-libp2p-autonat             stabilize
go-libp2p-autonat-svc         master
go-libp2p-blankhost           master
go-libp2p-circuit             master
go-libp2p-connmgr             master
go-libp2p-consensus           master
go-libp2p-core                stabilize
go-libp2p-daemon              master
go-libp2p-discovery           master
go-libp2p-examples            master
go-libp2p-gorpc               master
go-libp2p-kad-dht             tracer-more-logs
go-libp2p-kbucket             master
go-libp2p-loggables           master
go-libp2p-mplex               master
go-libp2p-nat                 master
go-libp2p-netutil             master
go-libp2p-peerstore           master
go-libp2p-pnet                master
go-libp2p-pubsub              master
go-libp2p-pubsub-router       master
go-libp2p-quic-transport      unspecified-addrs
go-libp2p-raft                master
go-libp2p-record              master
go-libp2p-routing-helpers     master
go-libp2p-secio               master
go-libp2p-swarm               master
go-libp2p-testing             master
go-libp2p-tls                 master
go-libp2p-transport-upgrader  master
go-libp2p-yamux               master
go-maddr-filter               master
go-mplex                      master
go-msgio                      master
go-multiaddr                  master
go-multiaddr-dns              master
go-multiaddr-fmt              master
go-multiaddr-net              master
go-multistream                master
go-nat                        master
go-reuseport                  master
go-reuseport-transport        master
go-sockaddr                   master
go-stream-muxer-multistream   master
go-tcp-transport              master
go-ws-transport               master
go-yamux                      master

A2: dht-tracer1/tracedht/tracedht --help output

> ./tracedht --help
SYNOPSIS
    tracedht - trace dht queries to the ipfs dht

USAGE
    tracedht [<opts>...] [<query>]

OPTIONS
    -h, --help           show usage
    --serve <addr>       run ctrl http server on <addr>
    --kad-alpha <int>    set kad-dht alpha value (default: 10)
    --bootstrap <addrs>  non-default bootstrap multiaddrs (newline delimited)
    --debug              enable debug logs
    --quic               use quic transport only (helps with fd limits)
    #todo -f, --logfile  file to store eventlogs in

QUERIES
    Please see the documentation for libp2p-kad-dht to find out
    what dht queries mean and do. This tool assumes extensive
    familiarity with libp2p-kad-dht.

    tracedht queries are libp2p-kad-dht queries, expressed in
    text, with the following formats:

      put-value <key> <value>
      get-value <key> <value>
      add-provider <cid>
      get-providers <cid>
      find-peer <peer-id>
      ping <peer-id>

    Queries can be run via the commandline, or via an api server
    that this tool runs.


EXAMPLES
    # run server at localhost:8080
    tracedht --serve ":8080"

    # run dht queries w/ alpha value of 15
    tracedht --kad-alpha 15

    # run a specific query, and then Exit
    tracedht find-peer

    # server example
    tracedht --serve :8080 &
    curl "http://localhost:8080/cmd?q=put-value+foo+bar"
    curl "http://localhost:8080/cmd?q=find-peer+<peer-id>"

    # save event logs
    tracedht --serve :8080 &
    curl "http://localhost:8080/events" | grep dht >eventlogs
    curl "http://localhost:8080/cmd?q=put-value+foo+bar"

A3: dht-tracer1/localdht/localdht --help output

> ./localdht --help
SYNOPSIS
    localdht - make a network of dht nodes

USAGE
    localdht [<opts>...] [<query>]

OPTIONS
    -h, --help        show usage
    -n <int>          number of dht nodes to run (default: 100)
    --debug           enable debug logging
    --quic            use quic transport only (helps w/ fd limits)
    --bootstrap-file  write bootstrap addresses to this file

EXAMPLES
    # run 100 dht nodes
    localdht