github.com/m-lab/locate@v0.17.6/DEVELOPMENT.md (about)

     1  # Setup for local development
     2  
     3  ## Redis & Locate Servers
     4  
     5  ```sh
     6  docker-compose build
     7  docker-compose up
     8  ```
     9  
    10  ## Heartbeats
    11  
    12  Use real machine names in order to reuse the public 'registration.json'. While
    13  the names are real, the statuses are not.
    14  
    15  You may need to run multiple heartbeat instances to simulate multiple machines.
    16  Each heartbeat service will need a unique prometheusx.listen-address to prevent
    17  conflicts.
    18  
    19  ```sh
    20  ./heartbeat -experiment=ndt \
    21    -heartbeat-url ws://localhost:8080/v2/platform/heartbeat \
    22    -hostname=mlab2-lga1t.mlab-sandbox.measurement-lab.org \
    23    -registration-url=https://siteinfo.mlab-oti.measurementlab.net/v2/sites/registration.json \
    24    -services 'ndt/ndt7=ws:///ndt/v7/download,ws:///ndt/v7/upload,wss:///ndt/v7/download,wss:///ndt/v7/upload' \
    25    -prometheusx.listen-address=:9991
    26  ```
    27  
    28  You may also construct your own registration.json file and provide this to the heartbeat:
    29  
    30  ```txt
    31    -registration-url=file://$PWD/registration.json \
    32  ```
    33  
    34  ## Fake service ports
    35  
    36  The heartbeat scans the local service port to determine if the service is
    37  healthy. Since we're faking everything, all we need to do is listen on the ports
    38  that the heartbeat is scanning. For example:
    39  
    40  ```sh
    41  ncat --broker --listen -p 80 &
    42  ncat --broker --listen -p 443 &
    43  ```
    44  
    45  The `--broker` flag will keep the process listening indefinitely.
    46  
    47  If the heartbeat does not detect a running service, the machine will be reported
    48  as unhealthy, and will not be returned by Locate under normal behavior.
    49  
    50  ## Local requests
    51  
    52  Once everything is running, you can make local requests to verify it is working
    53  as you expect. It will be necessary to provide location information since
    54  the location headers added by App Engine will be missing. For example:
    55  
    56  * http://localhost:8080/v2/nearest/ndt/ndt7?region=US-NJ
    57  
    58  ## Pitfalls
    59  
    60  Just as in production, the ready handler should return "ok". If it does not,
    61  there is either a problem communicating with your redis instance, or there may
    62  be corrupt or junk data in Redis that is confusing Locate. This can happen if
    63  you run locate and redis separately outside of docker-compose.
    64  
    65  ```sh
    66  curl --dump-header - localhost:8080/v2/ready
    67  ```
    68  
    69  ## Query Redis
    70  
    71  ```sh
    72  $ redis-cli --scan --pattern "*"
    73  "mlab1-lga0t.mlab-sandbox.measurement-lab.org"
    74  $ redis-cli --raw HGETALL mlab1-lga0t.mlab-sandbox.measurement-lab.org
    75  Health
    76  {"Score":1}
    77  Registration
    78  {"City":"New York","CountryCode":"US","ContinentCode":"NA","Experiment":"ndt","Hostname":"mlab1-lga0t.mlab-sandbox.measurement-lab.org","Latitude":40.7667,"Longitude":-73.8667,"Machine":"mlab1","Metro":"lga","Project":"mlab-sandbox","Probability":1,"Site":"lga0t","Type":"physical","Uplink":"10g","Services":{"ndt/ndt7":["ws:///ndt/v7/download","ws:///ndt/v7/upload","wss:///ndt/v7/download","wss:///ndt/v7/upload"]}}
    79  ```