Rewrite demo script

README.md

@@ -70,13 +70,13 @@ docker compose -f compose.dev.yaml watch
 `docker compose` will automatically reload containers when you make changes. The `JANUS_IMAGE` and
 `JANUS_MIGRATOR_IMAGE` variables are honored by `compose.dev.yaml`.
 
-Two Janus aggregators will be created for you, but are not automatically paired to divviup-api.
-Their information is:
-1. Address: `http://janus_1_aggregator:8080/aggregator-api`, Token: `0000`
-1. Address: `http://janus_2_aggregator:8080/aggregator-api`, Token: `0000`
+An account named `demo` is also automatically created. Two Janus aggregators will be created for
+you, and are automatically paired to divviup-api. Their information is:
 
-If you need to talk to these aggregators from outside compose's network namespace, e.g. with a
-testing client, they are mapped to `localhost:9001` and `localhost:9002`, respectively.
+| Name | Aggregator API address | Aggregator API auth token | Paired with | DAP API outside compose network |
+| ---- | ---------------------- | ------------------------- | ----------- | ------------------------------- |
+| `leader` | `http://janus_1_aggregator:8080/aggregator-api` | `0000` | Shared, first party | `localhost:9001` |
+| `helper` | `http://janus_2_aggregator:8080/aggregator-api` | `0000` | `demo` account | `localhost:9002` |
 
 If using the divviup CLI, consider compiling with the `--features admin` option. Also, set these
 environment variables.

cli/README.md

@@ -12,20 +12,69 @@ If you run into problems with the `aws-lc-rs` dependency, you can try building w
 
 Or you can download a binary for your OS and host architecture from our [releases](https://github.com/divviup/divviup-api/releases).
 
-### Command Line Tutorial
+### Divvi Up quickstart
 
-First, set an environment variable for the Divvi Up account and an API token. You can create an API token by logging into the [Divvi Up console](https://app.divviup.org).
+We'll walk through a simple exercise in which we will:
+
+- Run Divvi Up and a pair of aggregators locally in Docker
+- Shard some measurements into reports and upload them, simulating DAP clients
+- Collect the results of an aggregation
+
+To get started, you'll need:
+
+- A Unix like shell
+- A `divviup` binary (see instructions above)
+- A `compose.yaml` (you can use the one in this repository or the one you find alongside the `divviup` binaries on our [releases](https://github.com/divviup/divviup-api/releases) page)
+- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/).
+
+First, get Divvi Up running locally. In your shell, navigate to the directory containing `compose.yaml` and run:
+
+```sh
+docker compose up --wait
+```
+
+This will:
+
+- deploy two Janus aggregators to act as leader and helper in your tasks
+- deploy the Divvi Up control plane to coordinate the aggregators
+- pair the aggregators with the control plane to make them available for use in task definitions
+- create an account named "demo"
+
+Set an environment variable to direct `divviup` to use your local control plane and to use an empty
+API token:
 
 ```sh
-export DIVVIUP_TOKEN=YOUR_TOKEN_HERE
+export DIVVIUP_API_URL=http://localhost:8080
+export DIVVIUP_TOKEN=""
 ```
 
-Test the token by listing all accounts. Your account ID is inferred from the token.
+Next, obtain the ID of the demo account:
 
 ```sh
 divviup account list
 ```
 
+You should get a single account back with the name "demo", like this:
+
+```json
+[
+  {
+    "id": "8ea1fc65-a669-48dd-96ac-c920fcb0ae90",
+    "name": "demo",
+    "created_at": "2024-06-14T22:48:00.683659Z",
+    "updated_at": "2024-06-14T22:48:00.683659Z",
+    "admin": false
+  }
+]
+```
+
+Now, set an environment variable for the account ID:
+
+```sh
+# Substitute the account ID that was generated by your Divvi Up instance
+export DIVVIUP_ACCOUNT_ID=8ea1fc65-a669-48dd-96ac-c920fcb0ae90
+```
+
 List the aggregators and identify the ID of both a leader and a helper.
 
 ```sh
@@ -92,6 +141,7 @@ The output will contain JSON objects like:
 Set the two IDs into environment variables. NOTE: These IDs will vary based on your configuration.
 
 ```sh
+# Substitute the leader and helper aggregator IDs that were generated by your Divvi Up instance
 export LEADER_ID=3650870b-56e6-4eac-8944-b7ca36569b33
 export HELPER_ID=96301951-c848-4a57-b4f5-32812e4db1be
 ```
@@ -122,22 +172,25 @@ The output will be like:
   "token": "A6JDAYPiYDXmNyh-OpYXGw"
 }
 
-Saved new collector credential to /your/current/directory/collector-credential-<some-number>.json. Keep this file safe!
+Saved new collector credential to /your/current/directory/collector-credential-144.json. Keep this file safe!
 ```
 
+**Note**: This credential isn't sensitive because it's only useful in your local instance of Divvi Up. But collector credentials generated against the production service should be carefully managed. Consider using a password manager to protect them.
+
 Make a note of the path where the credential was saved, and save the collector credential ID to an environment variable.
 
 ```sh
-export COLLECTOR_CREDENTIAL_PATH=/your/current/directory/collector-credential-<some-number>.json
-export COLLECTOR_ID=0a0f8ea8-b603-4416-b138-b7f217153bb7
+# Substitute the collector credential path and ID that were generated by your Divvi Up instance
+export COLLECTOR_CREDENTIAL_PATH=/your/current/directory/collector-credential-144.json
+export COLLECTOR_CREDENTIAL_ID=0a0f8ea8-b603-4416-b138-b7f217153bb7
 ```
 
 Create the the histogram task. In this case the task is a set of values from 0 to 10 for use in collecting a net-promoter score for a survey.
 
 ```sh
  divviup task create --name net-promoter-score \
     --leader-aggregator-id $LEADER_ID --helper-aggregator-id $HELPER_ID \
-    --collector-credential-id $COLLECTOR_ID \
+    --collector-credential-id $COLLECTOR_CREDENTIAL_ID \
     --vdaf histogram --categorical-buckets 0,1,2,3,4,5,6,7,8,9,10 \
     --min-batch-size 100 --max-batch-size 200 --time-precision 60sec
 ```
@@ -191,6 +244,7 @@ The output will contain a JSON object:
 Save the ID of the task into an environment variable.
 
 ```sh
+# Substitute the task ID that was generated by your Divvi Up instance
 export TASK_ID=Siwa4QTEnQXMfRPyhir8AzS4EBqfTebmEzKfvajDgYk
 ```
 
@@ -199,7 +253,7 @@ Upload a random set of 150 metrics.
 ```sh
 for i in {1..150}; do
   measurement=$(( $RANDOM % 10 ))
-  divviup dap-client upload --task-id $TASK_ID  --measurement $measurement;
+  divviup dap-client upload --task-id $TASK_ID --measurement $measurement;
 done
 ```
 
@@ -223,4 +277,8 @@ Aggregation result: [14, 10, 10, 13, 13, 8, 16, 13, 9, 7, 0]
 collection: Collection { partial_batch_selector: PartialBatchSelector { batch_identifier: BatchId(wPLBlC6iHWp_YBBAYP_ig5nal0FOz1QlLSaC42U7sm0) }, report_count: 113, interval: (2024-06-05T21:31:00Z, TimeDelta { secs: 180, nanos: 0 }), aggregate_result: [14, 10, 10, 13, 13, 8, 16, 13, 9, 7, 0] }
 ```
 
+If you get an error like "The batch implied by the query is invalid", then the aggregators are still working on processing your uploaded reports. Given them a few more minutes.
+
 If you get fewer reports in the collection than you uploaded, that's because you sent the collection request too soon and not all the reports were prepared yet. Those reports will be available in a later collection, after enough additional reports are uploaded to meet the minimum batch size.
+
+Congratulations! You've just used secure multi-party computation to do a privacy-preserving aggregation over secret shares of measurements. Now you can try experimenting with different tasks. Try creating different histograms with different numbers of buckets, or see if you can use `Prio3SumVec` to compute sums over bit vectors.

compose.yaml

@@ -58,16 +58,20 @@ services:
   pair_aggregator:
     image: ${DIVVIUP_API_IMAGE:-us-west2-docker.pkg.dev/divviup-artifacts-public/divviup-api/divviup_api_integration_test:0.3.16}
     entrypoint:
-      - /divviup
-      - --url=http://localhost:8080
-      - --token=""
-      - aggregator
-      - create
-      - --name=leader
-      - --api-url=http://janus_1_aggregator:8080/aggregator-api
-      - --bearer-token=0000
-      - --first-party
-      - --shared
+      - /bin/sh
+      - -c
+      - |
+        /divviup --url=http://localhost:8080 --token="" \
+          aggregator create \
+          --name=leader --api-url=http://janus_1_aggregator:8080/aggregator-api \
+          --bearer-token=0000 \
+          --first-party --shared && \
+        /divviup --url=http://localhost:8080 --token="" \
+          account create demo && \
+        /divviup --url=http://localhost:8080 --token="" \
+          aggregator create \
+          --name=helper --api-url=http://janus_2_aggregator:8080/aggregator-api \
+          --bearer-token=0000
     network_mode: service:divviup_api
     depends_on:
       divviup_api: