[![Unit Tests]] [![System Tests]] [![Lint]] [![codecov]]
[WiP]
The IoTHM is a distributed IoT platform which combines information from different hardware sensors applied to home monitoring. The goal is to support embedded platforms such as ESP32 to monitor aspects like temperature, humidity, pressure and so on, and make the information available to be easily accessed and analyzed by using dashboards or even processed my Machine Learning models.
This is a open-source project based on many tools such as: Docker, Python, Django, PostgreSQL, Redis, Elasticsearch and so on. Here are the services which are part of the IoTHM:
- Events REST API, provides access to the monitoring data in a form of a REST API
- Events Database, database containing all the monitoring data
- Monitoring, centralized platform's log monitoring
- Sensoring, reads and sends the data from the hardware sensors to be processed
Detailed information about each service will be provided inside the respective folders.
To build and run the application, clone the repository and run in a terminal
from the same directory where the docker-compose-{environment}.yaml
file
is, where environment can be dev, test, prod or whatever:
$ docker-compose -f docker-compose-dev.yaml up
To stop the application, run from the same directory:
$ docker-compose stop
Each service is exposed through a specific port, after build and run it's possible to access the following:
- Data REST API, port 8000
- Elasticsearch, port 9200
- Kibana, port 5601
- PostgreSQL Database, port 5432
Detailed information about each service will be provided inside the respective folders.
All the logs are sent to an Elasticsearch instance. The main goal here is to provide a real time log stream that can be monitored using Kibana.
The file docker-compose-test.yaml
runs unit and system tests generating
the reports after that.
$ docker-compose -f docker-compose-test.yaml up
This should start the container, run the tests, generate the reports and exit.
The main
is a regular branch which always contains the latest
stable codebase and must never be broken.
The develop
is a regular branch which always contains the latest
development codebase and eventually can be broken. But you'll need to
accept the sombrero of shame if you do that.
The release
is a regular branch which contains a specific release
version. You must use the following name convention: release-X.Y.Z, where
X, Y and Z are: major, minor and patch version numbers.
The experimental
is a temporary branch which contains a new feature or
ideia that is not part of a release or sprint. You must use the following name
convention: experimental-brief-description.
The feature
is a temporary branch which contains a new feature under
development that latter will be merged against the development branch. You must
use the following name convention: feature-iothm-999-brief-description,
where iothm-999 must correspond to a existing numbered task on the project board.
The bugfix
is a temporary branch which contains necessary fix to be
applied after a specific release to be merged against the development branch.
You must use the following name convention: bugfix-iothm-999-brief-description,
where iothm-999 must correspond to a existing numbered task on the project board.
The hotfix
is a temporary branch which contains a critical fix to be
applied immediately and merged against the main and the development branches.
You must use the following name convention: hotfix-iothm-999-brief-description,
where iothm-999 must correspond to a existing numbered task on the project board.
Feel free to apply the labels from GitHub to the branches, they are very helpful.
The project uses the bump2version in order to control the version numbers following the semantic versioning 2.0.0.
After commit a modification (because the repository must be clean), you must update the version according to the following rules:
- Increment the
MAJOR
version when you make incompatible API changes. - Increment the
MINOR
version when you add functionality in a backwards compatible manner. - Increment the
PATCH
version when you make backward compatible bug fixes.
It's possible to perform a dry-run test without touch any file, for example with
a MINOR
, run:
$ bump2version --dry-run --verbose minor
To increment the MAJOR
version run:
$ bump2version major --commit
To increment the MINOR
version run:
$ bump2version minor --commit
To increment the PATCH
version run:
$ bump2version patch --commit
Then you can go ahead and commit again to send the updated versioning files.
The main
, develop
and release
branches have protection rules
against push.
In order to contribute you must create a new branch following the branching guideline and once your work is done, open a pull request from your branch to the develop branch.
The pull request will trigger the unit and system test suites automatically
and the code must pass all the tests and also be reviewed and approved by
at least one team member before merged in the develop branch (or even main
or release
in case of a *fix
).
Feel free to apply the labels from GitHub to the pull requests, they are very helpful.
This project uses pipenv and pre-commit in order to run some static checks and formatting on the code. After clone the repository you need to create a new virtual environment and install the dependencies:
$ pipenv shell
$ pipenv install --dev
$ pre-commit install
Every time you run the git commit
command the code will be checked. To
run the checking manually, run:
$ pre-commit run --all-files