Mainflux.mainflux/things/README.md

119 lines
8.0 KiB
Markdown
Raw Normal View History

# Things
2018-05-11 05:53:25 +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
- provision new things
2018-05-11 05:53:25 +08:00
- create new channels
- "connect" things into the channels
2018-05-11 05:53:25 +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.
| Variable | Description | Default |
|-----------------------------|------------------------------------------------------------------------|----------------|
| MF_THINGS_LOG_LEVEL | Log level for Things (debug, info, warn, error) | error |
| 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 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_CLIENT_TLS | Flag that indicates if TLS should be turned on | false |
| MF_THINGS_CA_CERTS | Path to trusted CAs in PEM format | |
| MF_THINGS_CACHE_URL | Cache database URL | localhost:6379 |
| MF_THINGS_CACHE_PASS | Cache database password | |
| MF_THINGS_CACHE_DB | Cache instance that should be used | 0 |
| MF_THINGS_ES_URL | Event store URL | localhost:6379 |
| MF_THINGS_ES_PASS | Event store password | |
| MF_THINGS_ES_DB | Event store instance that should be used | 0 |
| MF_THINGS_HTTP_PORT | Things service HTTP port | 8180 |
| MF_THINGS_AUTH_HTTP_PORT | Things service auth HTTP port | 8989 |
| MF_THINGS_AUTH_GRPC_PORT | Things service auth gRPC port | 8181 |
| MF_THINGS_SERVER_CERT | Path to server certificate in pem format | 8181 |
| MF_THINGS_SERVER_KEY | Path to server key in pem format | 8181 |
| MF_USERS_URL | Users service URL | localhost:8181 |
| MF_THINGS_SINGLE_USER_EMAIL | User email for single user mode (no gRPC communication with users) | |
| MF_THINGS_SINGLE_USER_TOKEN | User token for single user mode that should be passed in auth header | |
**Note** that if you want `things` service to have only one user locally, you should use `MF_THINGS_SINGLE_USER` env vars. By specifying these, you don't need `users` service in your deployment as it won't be used for authorization.
2018-05-11 05:53:25 +08:00
## Deployment
The service itself is distributed as Docker container. The following snippet
provides a compose file template that can be used to deploy the service container
locally:
```yaml
version: "2"
services:
things:
image: mainflux/things:[version]
2018-05-11 05:53:25 +08:00
container_name: [instance name]
ports:
- [host machine port]:[configured HTTP port]
environment:
MF_THINGS_LOG_LEVEL: [Things log level]
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]
MF_THINGS_DB: [Name of the database used by the service]
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-426 - Add optional MF_CA_CERTS env variable to allow GRPC client to use TLS certs (#430) * MF-426-Add optional MF_CA_CERTS env variable to allow GRPC client to use TLS certs Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * enable things client to be configured with a ca cert path Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * MF_CA_CERTS docs for http adapter and things service, additional logging and improved error handling when setting up TLS gRPC client Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * refactor things connect to separate function Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * getting-started updates, corrected things env variable Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * clarifying ca certs default functionality Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * configuring tls termination at service endpoint Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * enable TLS configuration for users and things Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * nginx forwarding Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * go imports Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * bad logging change Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * naming specifically to the http adapter component Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * updated tls keys, slightly different grpc configuration set localhost, users and things as subject alternative names Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * log message consistency Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * readme updates related to server ssl configuration Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * Trying to resolve confilcts Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * removing conflicting lines from docker-compose Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * adding back http-adapter configuration Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * slight readme update Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * readme tweaks Signed-off-by: nwest1 <nwest1@users.noreply.github.com>
2018-11-07 04:09:17 +08:00
MF_THINGS_CA_CERTS: [Path to trusted CAs in PEM format]
MF_THINGS_CACHE_URL: [Cache database URL]
MF_THINGS_CACHE_PASS: [Cache database password]
MF_THINGS_CACHE_DB: [Cache instance that should be used]
MF_THINGS_ES_URL: [Event store URL]
MF_THINGS_ES_PASS: [Event store password]
MF_THINGS_ES_DB: [Event store instance that should be used]
MF_THINGS_HTTP_PORT: [Service HTTP port]
MF_THINGS_AUTH_HTTP_PORT: [Service auth HTTP port]
MF_THINGS_AUTH_GRPC_PORT: [Service auth gRPC port]
MF-426 - Add optional MF_CA_CERTS env variable to allow GRPC client to use TLS certs (#430) * MF-426-Add optional MF_CA_CERTS env variable to allow GRPC client to use TLS certs Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * enable things client to be configured with a ca cert path Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * MF_CA_CERTS docs for http adapter and things service, additional logging and improved error handling when setting up TLS gRPC client Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * refactor things connect to separate function Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * getting-started updates, corrected things env variable Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * clarifying ca certs default functionality Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * configuring tls termination at service endpoint Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * enable TLS configuration for users and things Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * nginx forwarding Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * go imports Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * bad logging change Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * naming specifically to the http adapter component Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * updated tls keys, slightly different grpc configuration set localhost, users and things as subject alternative names Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * log message consistency Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * readme updates related to server ssl configuration Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * Trying to resolve confilcts Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * removing conflicting lines from docker-compose Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * adding back http-adapter configuration Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * slight readme update Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * readme tweaks Signed-off-by: nwest1 <nwest1@users.noreply.github.com>
2018-11-07 04:09:17 +08:00
MF_THINGS_SERVER_CERT: [String path to server cert in pem format]
MF_THINGS_SERVER_KEY: [String path to server key in pem format]
2018-05-11 05:53:25 +08:00
MF_USERS_URL: [Users service URL]
MF_THINGS_SECRET: [String used for signing tokens]
MF_THINGS_SINGLE_USER_EMAIL: [User email for single user mode (no gRPC communication with users)]
MF_THINGS_SINGLE_USER_TOKEN: [User token for single user mode that should be passed in auth header]
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
go get github.com/mainflux/mainflux
cd $GOPATH/src/github.com/mainflux/mainflux
# 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
MF_THINGS_LOG_LEVEL=[Things log level] 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] MF_THINGS_DB=[Name of the database used by the service] 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_HTTP_ADAPTER_CA_CERTS=[Path to trusted CAs in PEM format] MF_THINGS_CACHE_URL=[Cache database URL] MF_THINGS_CACHE_PASS=[Cache database password] MF_THINGS_CACHE_DB=[Cache instance that should be used] MF_THINGS_ES_URL=[Event store URL] MF_THINGS_ES_PASS=[Event store password] MF_THINGS_ES_DB=[Event store instance that should be used] MF_THINGS_HTTP_PORT=[Service HTTP port] MF_THINGS_AUTH_HTTP_PORT=[Service auth HTTP port] MF_THINGS_AUTH_GRPC_PORT=[Service auth gRPC port] MF_USERS_URL=[Users service URL] MF_THINGS_SERVER_CERT=[Path to server certificate] MF_THINGS_SERVER_KEY=[Path to server key] MF_THINGS_SINGLE_USER_EMAIL=[User email for single user mode (no gRPC communication with users)] MF_THINGS_SINGLE_USER_TOKEN=[User token for single user mode that should be passed in auth header] $GOBIN/mainflux-things
2018-05-11 05:53:25 +08:00
```
MF-426 - Add optional MF_CA_CERTS env variable to allow GRPC client to use TLS certs (#430) * MF-426-Add optional MF_CA_CERTS env variable to allow GRPC client to use TLS certs Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * enable things client to be configured with a ca cert path Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * MF_CA_CERTS docs for http adapter and things service, additional logging and improved error handling when setting up TLS gRPC client Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * refactor things connect to separate function Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * getting-started updates, corrected things env variable Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * clarifying ca certs default functionality Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * configuring tls termination at service endpoint Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * enable TLS configuration for users and things Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * nginx forwarding Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * go imports Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * bad logging change Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * naming specifically to the http adapter component Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * updated tls keys, slightly different grpc configuration set localhost, users and things as subject alternative names Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * log message consistency Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * readme updates related to server ssl configuration Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * Trying to resolve confilcts Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * removing conflicting lines from docker-compose Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * adding back http-adapter configuration Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * slight readme update Signed-off-by: nwest1 <nwest1@users.noreply.github.com> * readme tweaks Signed-off-by: nwest1 <nwest1@users.noreply.github.com>
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.
2018-05-11 05:53:25 +08:00
## Usage
For more information about service capabilities and its usage, please check out
the [API documentation](swagger.yaml).
[doc]: http://mainflux.readthedocs.io