122 lines
8.3 KiB
Markdown
122 lines
8.3 KiB
Markdown
# Clients
|
|
|
|
Users service provides an HTTP API for managing users. Through this API clients
|
|
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.
|
|
|
|
| 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 | "" |
|
|
|
|
## Deployment
|
|
|
|
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.
|
|
|
|
To start the service outside of the container, execute the following shell script:
|
|
|
|
```bash
|
|
# download the latest version of the service
|
|
git clone https://github.com/mainflux/mainflux
|
|
|
|
cd mainflux
|
|
|
|
# compile the service
|
|
make users
|
|
|
|
# copy binary to bin
|
|
make install
|
|
|
|
# set the environment variables and run the service
|
|
MF_USERS_LOG_LEVEL=[Users log level] \
|
|
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] \
|
|
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] \
|
|
MF_USERS_DB_NAME=[Name of the database used by the service] \
|
|
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] \
|
|
MF_JAEGER_URL=[Jaeger server URL] \
|
|
MF_SEND_TELEMETRY=[Send telemetry to Jaeger (true/false)] \
|
|
MF_USERS_INSTANCE_ID=[Instance ID] \
|
|
$GOBIN/mainflux-users
|
|
```
|
|
|
|
If `MF_EMAIL_TEMPLATE` doesn't point to any file service will function but password reset functionality will not work.
|
|
|
|
## Usage
|
|
|
|
For more information about service capabilities and its usage, please check out
|
|
the [API documentation](https://api.mainflux.io/?urls.primaryName=users-openapi.yml).
|
|
|
|
[doc]: https://docs.mainflux.io
|