HuBMAP and SenNet UUID API

The uuid-api service is a restful web service used to create and query UUIDs used across HuBMAP. Three types of IDs are supported:

• uuid: Standard randomly generated 128 bit UUIDs represented as 32 hexadecimal digits. These are generated by the service.
• hubmap_id: A randomly generated unique id that can be used to construct a HuBMAP DOI in the format ######.XXXX.###.
• submission_id: Only gets generated for Donor and Sample, e.g., UFL0007

Overview of tools

• Docker Engine
• Docker Compose

Note: Docker Compose requires Docker to be installed and running first.

Docker post-installation configurations

The Docker daemon binds to a Unix socket instead of a TCP port. By default that Unix socket is owned by the user root and other users can only access it using sudo. The Docker daemon always runs as the root user. If you don’t want to preface the docker command with sudo, add users to the docker group:

sudo usermod -aG docker $USER

Then log out and log back in so that your group membership is re-evaluated. If testing on a virtual machine, it may be necessary to restart the virtual machine for changes to take effect.

Note: the following instructions with docker commands are based on managing Docker as a non-root user.

Docker build for local/DEV development

There are a few configurable environment variables to keep in mind:

• COMMONS_BRANCH: build argument only to be used during image creation when we need to use a branch of commons from github rather than the published PyPI package. Default to master branch if not set or null.
• HOST_UID: the user id on the host machine to be mapped to the container.
• HOST_GID: the user's group id on the host machine to be mapped to the container.

We can set and verify the environment variable like below:

export COMMONS_BRANCH=main
echo $COMMONS_BRANCH

Note: Environment variables set like this are only stored temporally. When you exit the running instance of bash by exiting the terminal, they get discarded. So for rebuilding the docker image, we'll need to make sure to set the environment variables again if necessary.

cd docker
./docker-development.sh [check|config|build|start|stop|down]

Docker build for deployment on PROD

cd hubmap-docker
./docker-deployment.sh [start|stop|down]

Development process

To work on features in the development environment before ready for testing and releasing

• Make new feature branches off the main branch
• Make PRs to dev-integrate
• As a codeowner, Zhou is automatically assigned as a reviewer to each PR. When all other reviewers have approved, he will approve as well, merge to devel, and redeploy the DEV instance.
• When a feature branch is ready for testing and release, make a PR to main for deployment and testing on the TEST infrastructure as above.

Updating API Documentation

The documentation for the API calls is hosted on SmartAPI. Modifying the uuid-api-spec.yaml file and committing the changes to GitHub should update the API shown on SmartAPI. SmartAPI allows users to register API documents. The documentation is associated with this GitHub account: [email protected].