2018-05-16 20:28:41 +08:00
# Things
2018-05-11 05:53:25 +08:00
2019-04-20 20:09:11 +08:00
Things service provides an HTTP API for managing platform resources: things and channels.
Through this API clients are able to do the following actions:
2018-05-11 05:53:25 +08:00
2019-04-20 20:09:11 +08:00
- provision new things
2018-05-11 05:53:25 +08:00
- create new channels
2018-05-16 20:28:41 +08:00
- "connect" things into the channels
2018-05-11 05:53:25 +08:00
2018-05-16 20:28:41 +08:00
For an in-depth explanation of the aforementioned scenarios, as well as thorough
2018-05-11 05:53:25 +08:00
understanding of Mainflux, please check out the [official documentation][doc].
## 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.
2023-08-17 01:11:33 +08:00
| Variable | Description | Default |
| --------------------------------- | ----------------------------------------------------------------------- | ------------------------------ |
| MF_THINGS_LOG_LEVEL | Log level for Things (debug, info, warn, error) | info |
| MF_THINGS_HTTP_HOST | Things service HTTP host | localhost |
| MF_THINGS_HTTP_PORT | Things service HTTP port | 9000 |
| MF_THINGS_SERVER_CERT | Path to the PEM encoded server certificate file | "" |
| MF_THINGS_SERVER_KEY | Path to the PEM encoded server key file | "" |
| MF_THINGS_AUTH_GRPC_HOST | Things service gRPC host | localhost |
| MF_THINGS_AUTH_GRPC_PORT | Things service gRPC port | 7000 |
| MF_THINGS_AUTH_GRPC_SERVER_CERT | Path to the PEM encoded server certificate file | "" |
| MF_THINGS_AUTH_GRPC_SERVER_KEY | Path to the PEM encoded server key file | "" |
| MF_THINGS_DB_HOST | Database host address | localhost |
| MF_THINGS_DB_PORT | Database host port | 5432 |
| MF_THINGS_DB_USER | Database user | mainflux |
| MF_THINGS_DB_PASS | Database password | mainflux |
| MF_THINGS_DB_NAME | Name of the database used by the service | things |
| MF_THINGS_DB_SSL_MODE | Database connection SSL mode (disable, require, verify-ca, verify-full) | disable |
| MF_THINGS_DB_SSL_CERT | Path to the PEM encoded certificate file | "" |
| MF_THINGS_DB_SSL_KEY | Path to the PEM encoded key file | "" |
| MF_THINGS_DB_SSL_ROOT_CERT | Path to the PEM encoded root certificate file | "" |
| MF_THINGS_CACHE_URL | Cache database URL | localhost:6379 |
| MF_THINGS_CACHE_PASS | Cache database password | "" |
| MF_THINGS_CACHE_DB | Cache instance name | 0 |
| MF_THINGS_CACHE_KEY_DURATION | Cache key duration in seconds | 3600 |
| MF_THINGS_ES_URL | Event store URL | localhost:6379 |
| MF_THINGS_ES_PASS | Event store password | "" |
| MF_THINGS_ES_DB | Event store instance name | 0 |
| MF_THINGS_STANDALONE_ID | User ID for standalone mode (no gRPC communication with users) | "" |
| MF_THINGS_STANDALONE_TOKEN | User token for standalone mode that should be passed in auth header | "" |
| MF_JAEGER_URL | Jaeger server URL | http://jaeger:14268/api/traces |
| MF_AUTH_GRPC_URL | Users service gRPC URL | localhost:7001 |
| MF_AUTH_GRPC_TIMEOUT | Users service gRPC request timeout in seconds | 1s |
| MF_AUTH_GRPC_CLIENT_TLS | Enable TLS for gRPC client | false |
| MF_AUTH_GRPC_CA_CERT | Path to the CA certificate file | "" |
| MF_SEND_TELEMETRY | Send telemetry to mainflux call home server. | true |
| MF_THINGS_INSTANCE_ID | Things instance ID | "" |
2021-10-11 22:08:26 +08:00
2023-08-17 01:11:33 +08:00
**Note** that if you want `thin gs` service to have only one user locally, you should use `MF_THINGS_STANDALONE` env vars. By specifying these, you don't need `auth` service in your deployment for users' authorization.
2018-05-11 05:53:25 +08:00
## Deployment
2023-07-31 20:38:35 +08:00
The service itself is distributed as Docker container. Check the [`things ` ](https://github.com/mainflux/mainflux/blob/master/docker/docker-compose.yml#L167-L194 ) service section in
2021-02-02 23:26:02 +08:00
docker-compose to see how service is deployed.
2018-05-11 05:53:25 +08:00
To start the service outside of the container, execute the following shell script:
```bash
# download the latest version of the service
2019-11-27 22:29:34 +08:00
git clone https://github.com/mainflux/mainflux
2018-05-11 05:53:25 +08:00
2019-11-27 22:29:34 +08:00
cd mainflux
2018-05-11 05:53:25 +08:00
2018-05-16 20:28:41 +08:00
# compile the things
make things
2018-05-11 05:53:25 +08:00
# copy binary to bin
make install
# set the environment variables and run the service
2020-04-07 18:02:17 +08:00
MF_THINGS_LOG_LEVEL=[Things log level] \
2023-07-31 20:38:35 +08:00
MF_THINGS_STANDALONE_ID=[User ID for standalone mode (no gRPC communication with auth)] \
MF_THINGS_STANDALONE_TOKEN=[User token for standalone mode that should be passed in auth header] \
MF_THINGS_CACHE_KEY_DURATION=[Cache key duration in seconds] \
MF_THINGS_HTTP_HOST=[Things service HTTP host] \
MF_THINGS_HTTP_PORT=[Things service HTTP port] \
MF_THINGS_HTTP_SERVER_CERT=[Path to server certificate in pem format] \
MF_THINGS_HTTP_SERVER_KEY=[Path to server key in pem format] \
2023-08-17 01:11:33 +08:00
MF_THINGS_AUTH_GRPC_HOST=[Things service gRPC host] \
MF_THINGS_AUTH_GRPC_PORT=[Things service gRPC port] \
MF_THINGS_AUTH_GRPC_SERVER_CERT=[Path to server certificate in pem format] \
MF_THINGS_AUTH_GRPC_SERVER_KEY=[Path to server key in pem format] \
2020-04-07 18:02:17 +08:00
MF_THINGS_DB_HOST=[Database host address] \
MF_THINGS_DB_PORT=[Database host port] \
MF_THINGS_DB_USER=[Database user] \
MF_THINGS_DB_PASS=[Database password] \
2023-07-31 20:38:35 +08:00
MF_THINGS_DB_NAME=[Name of the database used by the service] \
2020-04-07 18:02:17 +08:00
MF_THINGS_DB_SSL_MODE=[SSL mode to connect to the database with] \
MF_THINGS_DB_SSL_CERT=[Path to the PEM encoded certificate file] \
MF_THINGS_DB_SSL_KEY=[Path to the PEM encoded key file] \
MF_THINGS_DB_SSL_ROOT_CERT=[Path to the PEM encoded root certificate file] \
MF_THINGS_CACHE_URL=[Cache database URL] \
MF_THINGS_CACHE_PASS=[Cache database password] \
MF_THINGS_CACHE_DB=[Cache instance name] \
MF_THINGS_ES_URL=[Event store URL] \
MF_THINGS_ES_PASS=[Event store password] \
MF_THINGS_ES_DB=[Event store instance name] \
2023-06-14 18:40:37 +08:00
MF_AUTH_GRPC_URL=[Users service gRPC URL] \
MF_AUTH_GRPC_TIMEOUT=[Users service gRPC request timeout in seconds] \
2023-07-31 20:38:35 +08:00
MF_AUTH_GRPC_CLIENT_TLS=[Enable TLS for gRPC client] \
MF_AUTH_GRPC_CA_CERT=[Path to trusted CA certificate file] \
MF_JAEGER_URL=[Jaeger server URL] \
MF_SEND_TELEMETRY=[Send telemetry to mainflux call home server] \
MF_THINGS_INSTANCE_ID=[Things instance ID] \
2020-04-07 18:02:17 +08:00
$GOBIN/mainflux-things
2018-05-11 05:53:25 +08:00
```
2018-11-07 04:09:17 +08:00
Setting `MF_THINGS_CA_CERTS` expects a file in PEM format of trusted CAs. This will enable TLS against the Users gRPC endpoint trusting only those CAs that are provided.
2021-10-11 22:08:26 +08:00
In constrained environments, sometimes it makes sense to run Things service as a standalone to reduce network traffic and simplify deployment. This means that Things service
operates only using a single user and is able to authorize it without gRPC communication with Auth service.
To run service in a standalone mode, set `MF_THINGS_STANDALONE_EMAIL` and `MF_THINGS_STANDALONE_TOKEN` .
2018-05-11 05:53:25 +08:00
## Usage
For more information about service capabilities and its usage, please check out
2021-06-23 19:31:46 +08:00
the [API documentation ](https://api.mainflux.io/?urls.primaryName=things-openapi.yml ).
2018-05-11 05:53:25 +08:00
2021-06-23 19:31:46 +08:00
[doc]: https://docs.mainflux.io
