Project and Docker naming and versions
This document shares the best practices of naming and versioning a module and its Docker image.
There is no strict convention regarding naming modules and their images, but described bellow are some rules of a good practice that we strongly recommend to everyone. Remember, the best names are always self-explanatory!
The unique identity of a module is comprised of the moduleName, a string, and the versionName, also a string. The combination of moduleName and versionName uniquely identifies the module across all locations. This consistency prevents ambiguity to users and those who might need to debug an edge application.
The module is registered in the platform according to the database entry with the following fields;
In the version control platform such as GitHub, the moduleName is the name of the repository. The versionName is the tag.
We recommend that releases should always be tagged from
In DockerHub, the moduleName is the name of the repository. The versionName is the image tag.
It is best practice to remove the
latesttag from DockerHub.
To comply with the above consistent approach to naming and versioning, the following recipe describes how to release a new version of a module.
Given a GitHub repo with the module code:
- 1.Optionally create a branch from
mainand name it as required
- 2.(Update code as required)
- 3.Update the
Module.yamland change the
- 4.When complete, merge this branch into main
- 5.In GitHub - go to tags, and create a new release, with the tag
- 6.Build and publish the image to Dockerhub with the same tag
- 7.Register the module with weeve, using the
The best approach would be to choose a module name that best describes its purpose. Similarly to choosing the names for your methods and variables when you code, a module name should be short and clear. Remember that very often the module will be used by your colleagues, who will be building weeve data services, or external users if you decide to make your module public on our platform. They should be able to get a good sense of what your module does just by looking at its name in Designer section of weeve IoT Platform and without a further need to explore the module documentation.
Let's look at some examples of our modules and their names:
- HTTP Egress - is a module outputting data from a data service to some endpoint over an HTTP protocol,
We strongly recommend making your module's Docker image name composed of your (or your organization's) name and the module name
<organization_name>/<module_name>. This way your modules could be easily recognized on devices that use them.
Let's look at the same modules as above and their Docker images names:
- MQTT Ingress:
- moduleName: mqtt-ingress
- Docker image name: weevenetwork/mqtt-ingress
- Camera Capture:
- moduleName: camera-capture
- Docker image name: weevenetwork/camera-capture
- Comparison Filter:
- moduleName: comparison-filter
- Docker image name: weevenetwork/comparison-filter
- HTTP Egress:
- moduleName: http-egress
- Docker image name: weevenetwork/http-egress
- Slack Alert:
- moduleName: slack-alert
- Docker image name: weevenetwork/slack-alert