Skip to content

Development Guide

Jump to bottom
Adam Stallard edited this page Sep 27, 2024 · 56 revisions

Development guide

The purpose of this guide is to help developers establish a BrightID-Node workflow.

Docker install/setup:

ArangoDB-Docker Image

To pull the official arangodb image from https://hub.docker.com/_/arangodb/ , execute

docker pull arangodb

Local Foxx Directory

Select a local directory as a bind mount for the foxx application directory. This directory must exist on your local filesystem. For example: FOXX_APPS=/home/docker/brightid/arangodb-apps. If you're using macOS, you might need to add that directory to the "File Sharing" tab so it can be bind mounted.

docker run

The following command will create a volume named "arangodb" to hold the DB files, so they persist even if the container is removed or updated. It creates a bind mount for the foxx application directory to the local foxx directory, so you can work on the foxx apps outside of docker.

docker run -d -e ARANGO_NO_AUTH=1 -e ARANGO_STORAGE_ENGINE=rocksdb -p 8529:8529 -v arangodb:/var/lib/arangodb3 -v $FOXX_APPS:/var/lib/arangodb3-apps --name arango arangodb

Upgrading arangodb while preserving data

If you're already developing locally and want to upgrade arangodb to the latest version, just append --database.auto-upgrade true to the end of the above docker run command. The container will exit immediately after upgrading the database volumes. Use docker rm arango to remove the container, then re-run the above docker run command without --database.auto-upgrade true.

ArangoDB web interface

open http://localhost:8529 in your browser

Foxx initial deployment

Go to "Services", "Add Service" and "Upload" the brightid5.zip file from https://github.com/BrightID/BrightID-Node/tree/master/web_services/foxx, and then "Install" the service and use /brightid5 as "Mount Point".

Upload and install apply5.zip file from the same path in the same way and use /apply5 as "Mount Point".

Repeat this for brightid6.zip (/brightid6) and apply6.zip (/apply6).

"brightid" vs "apply" foxx services

The brightid service provides a public API with different endpoints for BrightID mobile clients, but the apply service provides an internal API with a single endpoint for use by the consensus service run by the BrightID Node.

Consensus service use the apply service to apply operations to the database after all the nodes in BrightID network reached consensus over the operation. To avoid redundancy in coding, both brightid and apply services share the same js modules and the only difference between them is that:

  1. apply doesn't have tests folder (the tests/operations.js in brightid test this service too)
  2. apply has a different manifest.json file
  3. The manifest.json for apply uses apply.js as the main script for specifying endpoints

Foxx app development

Settings

Under "Settings" in the both of brightid and apply services, turn on development mode using "Set Development."

Configure the node settings. You can do this as described in the installation guide. Specifically you will need to set BN_SEED operationsTimeWindow operationsLimit and appsOperationsLimit. These can be set in the config.env file or under "Settings" in the fox services of the ArangoDB interface.

Default Values
  • BN_SEED: you can create a random Nacl keypair here and use the base64 representation of the public key as a secure seed phrase.
  • operationsTimeWindow: 900
  • operationsLimit: 60
  • appsOperationsLimit: 500

Editing

In the $FOXX_APPS directory, navigate to the _db\_system\brightid\APP sub-directory. Make changes to the javascript files, including tests. Changes will be hot loaded so you can see them in the app immediately.

Update the _db\_system\apply\APP folder with the newly changed js file to keep apply and brightid js files exactly the same (except for test files).

Testing changes in development mode

To run tests, go to "Settings" in the brightid service and click the beaker icon. To test the API, go to "API".

It's helpful to have two tabs open:

  1. http://localhost:8529/_db/_system/_admin/aardvark/index.html#service/%2Fbrightid* open to the API tab for testing the API or the Settings tab for running tests
  2. http://localhost:8529/_db/_system/_admin/aardvark/index.html#logs

Go to the first tab to test your change. If there aren't any test results, go to the second tab and check the log for errors.

Pushing Foxx changes to Github

  1. Under "Settings" for both brightid and apply services, click "download" to download .zip files.
  2. Navigate to your local clone of the https://github.com/BrightID/BrightID-Node/tree/master/web_services/foxx directory.
  3. Delete the existing brightid_* directory.
  4. Unzip the .zip file to create a new brightid_* directory.
  5. Replace old brightid_.zip and apply_.zip files with downloaded files. You might have to rename the files. For example, if the file downloaded from Foxx is brightid6_6.17.2.zip rename it to brightid6.zip to match what's in Github.
  6. Commit and push to Github.

Running a test server

Building docker images from the latest code

Get the latest code

git clone https://github.com/BrightID/BrightID-Node
cd BrightID-Node

Or

cd BrightID-Node
git pull

build

docker-compose build

Running the services

docker-compose up -d

Resources

Clone this wiki locally