Mainflux.mainflux/twins
Dušan Borovčanin 516c02bebe
MF-1378 - Update dependencies (#1379)
* Update dependencies

Signed-off-by: dusanb94 <dusan.borovcanin@mainflux.com>

* Fix compose files and configs

Signed-off-by: dusanb94 <dusan.borovcanin@mainflux.com>

* Upgrade image versions

Signed-off-by: dusanb94 <dusan.borovcanin@mainflux.com>

* Update Postgres version

Signed-off-by: dusanb94 <dusan.borovcanin@mainflux.com>

* Update test dependencies

Signed-off-by: dusanb94 <dusan.borovcanin@mainflux.com>

* Fix fkey error handling

Signed-off-by: dusanb94 <dusan.borovcanin@mainflux.com>
2021-05-20 20:53:56 +02:00
..
api MF-1368 - Add internal http api package for query params reading (#1384) 2021-03-23 11:48:05 +01:00
mocks NOISSUE - Fix run script and compiler warnings (#1336) 2021-01-26 01:07:06 +01:00
mongodb NOISSUE - Upgrade Mongo, Cassandra and Influx docker images (#1354) 2021-02-05 12:32:21 +01:00
redis MF-1378 - Update dependencies (#1379) 2021-05-20 20:53:56 +02:00
tracing MF-1180 - Add redis based twins and states cache (#1184) 2020-06-05 11:42:16 +02:00
README.md MF-1342 - Use environment variables in docker-compose to use tagged version of image (#1343) 2021-02-02 16:26:02 +01:00
doc.go MF-995 - Add Twins tests for endpoint list twins and list states (#1174) 2020-05-18 18:46:50 +02:00
openapi.yml MF-1276 - Fix openapi IDs and Keys format (#1338) 2021-01-27 11:42:55 +01:00
service.go NOISSUE - Rename package aliases uuidProvider into uuid (#1323) 2021-01-17 23:12:45 +01:00
service_test.go NOISSUE - Add subtopic wildcard for twin attribute's definition (#1214) 2020-07-09 12:18:19 +02:00
states.go MF-1180 - Add redis based twins and states cache (#1184) 2020-06-05 11:42:16 +02:00
twins.go MF-1180 - Add redis based twins and states cache (#1184) 2020-06-05 11:42:16 +02:00

README.md

Twins

Service twins is used for CRUD and update of digital twins. Twin is a semantic representation of a real world data system consisting of data producers and consumers. It stores the sequence of attribute based definitions of a system and refers to a time series of definition based states that store the system historical data.

Configuration

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

Variable Description Default
MF_TWINS_LOG_LEVEL Log level for twin service (debug, info, warn, error) error
MF_TWINS_HTTP_PORT Twins service HTTP port 9021
MF_TWINS_SERVER_CERT Path to server certificate in PEM format
MF_TWINS_SERVER_KEY Path to server key in PEM format
MF_JAEGER_URL Jaeger server URL
MF_TWINS_DB Database name mainflux
MF_TWINS_DB_HOST Database host address localhost
MF_TWINS_DB_PORT Database host port 27017
MF_TWINS_SINGLE_USER_EMAIL User email for single user mode (no gRPC communication with users)
MF_TWINS_SINGLE_USER_TOKEN User token for single user mode that should be passed in auth header
MF_TWINS_CLIENT_TLS Flag that indicates if TLS should be turned on false
MF_TWINS_CA_CERTS Path to trusted CAs in PEM format
MF_TWINS_CHANNEL_ID NATS notifications channel ID
MF_NATS_URL Mainflux NATS broker URL nats://localhost:4222
MF_AUTH_GRPC_URL Auth service gRPC URL localhost:8181
MF_AUTH_GRPC_TIMEOUT Auth service gRPC request timeout in seconds 1s
MF_TWINS_CACHE_URL Cache database URL localhost:6379
MF_TWINS_CACHE_PASS Cache database password
MF_TWINS_CACHE_DB Cache instance name 0

Deployment

The service itself is distributed as Docker container. Check the twins service section in docker-compose to see how service is deployed.

To start the service outside of the container, execute the following shell script:

# download the latest version of the service
go get github.com/mainflux/mainflux

cd $GOPATH/src/github.com/mainflux/mainflux

# compile the twins
make twins

# copy binary to bin
make install

# set the environment variables and run the service
MF_TWINS_LOG_LEVEL: [Twins log level] \
MF_TWINS_HTTP_PORT: [Service HTTP port] \
MF_TWINS_SERVER_CERT: [String path to server cert in pem format] \
MF_TWINS_SERVER_KEY: [String path to server key in pem format] \
MF_JAEGER_URL: [Jaeger server URL] MF_TWINS_DB: [Database name] \
MF_TWINS_DB_HOST: [Database host address] \
MF_TWINS_DB_PORT: [Database host port] \
MF_TWINS_SINGLE_USER_EMAIL: [User email for single user mode] \
MF_TWINS_SINGLE_USER_TOKEN: [User token for single user mode] \
MF_TWINS_CLIENT_TLS: [Flag that indicates if TLS should be turned on] \
MF_TWINS_CA_CERTS: [Path to trusted CAs in PEM format] \
MF_TWINS_CHANNEL_ID: [NATS notifications channel ID] \
MF_NATS_URL: [Mainflux NATS broker URL] \
MF_AUTH_GRPC_URL: [Auth service gRPC URL] \
MF_AUTH_GRPC_TIMEOUT: [Auth service gRPC request timeout in seconds] \
$GOBIN/mainflux-twins

Usage

Starting twins service

The twins service publishes notifications on a NATS subject of the format channels.<MF_TWINS_CHANNEL_ID>.messages.<twinID>.<crudOp>, where crudOp stands for the crud operation done on twin - create, update, delete or retrieve - or state - save state. In order to use twin service notifications, one must inform it - via environment variables - about the Mainflux channel used for notification publishing. You must use an already existing channel, since you cannot know in advance or set the channel ID (Mainflux does it automatically).

To set the environment variable, please go to .env file and set the following variable:

MF_TWINS_CHANNEL_ID=

with the corresponding values of the desired channel. If you are running mainflux natively, than do the same thing in the corresponding console environment.

For more information about service capabilities and its usage, please check out the API documentation.