2023-06-14 18:40:37 +08:00
# Clients
2018-05-11 05:53:25 +08:00
2019-04-20 20:09:11 +08:00
Users service provides an HTTP API for managing users. Through this API clients
2018-05-11 05:53:25 +08:00
are able to do the following actions:
- register new accounts
- obtain access tokens
- verify access tokens
For in-depth explanation of the aforementioned scenarios, as well as thorough
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-07-31 20:38:35 +08:00
| Variable | Description | Default |
| ------------------------------- | ----------------------------------------------------------------------- | ------------------------------ |
| MF_USERS_LOG_LEVEL | Log level for Users (debug, info, warn, error) | info |
| MF_USERS_SECRET_KEY | Default secret key used to generate tokens | mainflux |
| MF_USERS_ADMIN_EMAIL | Default user, created on startup | admin@example.com |
| MF_USERS_ADMIN_PASSWORD | Default user password, created on startup | 12345678 |
| MF_USERS_PASS_REGEX | Password regex | `^.{8,}$` |
| MF_USERS_ACCESS_TOKEN_DURATION | Duration for an access token to be valid | 15m |
| MF_USERS_REFRESH_TOKEN_DURATION | Duration for a refresh token to be valid | 24h |
| MF_TOKEN_RESET_ENDPOINT | Password request reset endpoint, for constructing link | /reset-request |
| MF_USERS_HTTP_HOST | Users service HTTP host | localhost |
| MF_USERS_HTTP_PORT | Users service HTTP port | 9002 |
| MF_USERS_HTTP_SERVER_CERT | Path to server certificate in pem format | "" |
| MF_USERS_HTTP_SERVER_KEY | Path to server key in pem format | "" |
| MF_USERS_GRPC_HOST | Users service GRPC host | localhost |
| MF_USERS_GRPC_PORT | Users service GRPC port | 7001 |
| MF_USERS_GRPC_SERVER_CERT | Path to server certificate in pem format | "" |
| MF_USERS_GRPC_SERVER_KEY | Path to server key in pem format | "" |
| MF_USERS_DB_HOST | Database host address | localhost |
| MF_USERS_DB_PORT | Database host port | 5432 |
| MF_USERS_DB_USER | Database user | mainflux |
| MF_USERS_DB_PASS | Database password | mainflux |
| MF_USERS_DB_NAME | Name of the database used by the service | users |
| MF_USERS_DB_SSL_MODE | Database connection SSL mode (disable, require, verify-ca, verify-full) | disable |
| MF_USERS_DB_SSL_CERT | Path to the PEM encoded certificate file | "" |
| MF_USERS_DB_SSL_KEY | Path to the PEM encoded key file | "" |
| MF_USERS_DB_SSL_ROOT_CERT | Path to the PEM encoded root certificate file | "" |
| MF_EMAIL_HOST | Mail server host | localhost |
| MF_EMAIL_PORT | Mail server port | 25 |
| MF_EMAIL_USERNAME | Mail server username | |
| MF_EMAIL_PASSWORD | Mail server password | |
| MF_EMAIL_FROM_ADDRESS | Email "from" address | |
| MF_EMAIL_FROM_NAME | Email "from" name | |
| MF_EMAIL_TEMPLATE | Email template for sending emails with password reset link | email.tmpl |
| MF_JAEGER_URL | Jaeger server URL | http://jaeger:14268/api/traces |
| MF_SEND_TELEMETRY | Send telemetry to mainflux call home server. | true |
| MF_INSTANCE_ID | Mainflux instance ID | "" |
2018-05-11 05:53:25 +08:00
## Deployment
2023-06-14 18:40:37 +08:00
The service itself is distributed as Docker container. Check the [`users` ](https://github.com/mainflux/mainflux/blob/master/docker/docker-compose.yml#L109-L143 ) service section in 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
2019-04-20 20:09:11 +08:00
# compile the service
2018-05-11 05:53:25 +08:00
make users
# copy binary to bin
make install
# set the environment variables and run the service
2021-02-02 23:26:02 +08:00
MF_USERS_LOG_LEVEL=[Users log level] \
2023-07-31 20:38:35 +08:00
MF_USERS_SECRET_KEY=[Secret key used to generate tokens] \
MF_USERS_ADMIN_EMAIL=[Default user, created on startup] \
MF_USERS_ADMIN_PASSWORD=[Default user password, created on startup] \
MF_USERS_PASS_REGEX=[Password regex] \
MF_USERS_ACCESS_TOKEN_DURATION=[Duration for an access token to be valid] \
MF_USERS_REFRESH_TOKEN_DURATION=[Duration for a refresh token to be valid] \
MF_TOKEN_RESET_ENDPOINT=[Password reset token endpoint] \
MF_USERS_HTTP_HOST=[Service HTTP host] \
MF_USERS_HTTP_PORT=[Service HTTP port] \
MF_USERS_HTTP_SERVER_CERT=[Path to server certificate] \
MF_USERS_HTTP_SERVER_KEY=[Path to server key] \
MF_USERS_GRPC_HOST=[Service GRPC host] \
MF_USERS_GRPC_PORT=[Service GRPC port] \
MF_USERS_GRPC_SERVER_CERT=[Path to server certificate] \
MF_USERS_GRPC_SERVER_KEY=[Path to server key] \
2021-02-02 23:26:02 +08:00
MF_USERS_DB_HOST=[Database host address] \
MF_USERS_DB_PORT=[Database host port] \
MF_USERS_DB_USER=[Database user] \
MF_USERS_DB_PASS=[Database password] \
2023-07-31 20:38:35 +08:00
MF_USERS_DB_NAME=[Name of the database used by the service] \
2021-02-02 23:26:02 +08:00
MF_USERS_DB_SSL_MODE=[SSL mode to connect to the database with] \
MF_USERS_DB_SSL_CERT=[Path to the PEM encoded certificate file] \
MF_USERS_DB_SSL_KEY=[Path to the PEM encoded key file] \
MF_USERS_DB_SSL_ROOT_CERT=[Path to the PEM encoded root certificate file] \
MF_EMAIL_HOST=[Mail server host] \
MF_EMAIL_PORT=[Mail server port] \
MF_EMAIL_USERNAME=[Mail server username] \
MF_EMAIL_PASSWORD=[Mail server password] \
MF_EMAIL_FROM_ADDRESS=[Email from address] \
MF_EMAIL_FROM_NAME=[Email from name] \
MF_EMAIL_TEMPLATE=[Email template file] \
2023-07-31 20:38:35 +08:00
MF_JAEGER_URL=[Jaeger server URL] \
MF_SEND_TELEMETRY=[Send telemetry to Jaeger (true/false)] \
MF_USERS_INSTANCE_ID=[Instance ID] \
2021-02-02 23:26:02 +08:00
$GOBIN/mainflux-users
2018-05-11 05:53:25 +08:00
```
2019-11-11 19:13:48 +08:00
If `MF_EMAIL_TEMPLATE` doesn't point to any file service will function but password reset functionality will not work.
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=users-openapi.yml ).
2018-05-11 05:53:25 +08:00
2023-07-31 20:38:35 +08:00
[doc]: https://docs.mainflux.io
