uiconfigs

README

UI Configs Service

The UI Configs service persists and manages UI configuration settings scoped per organization and per thing. Configuration payloads are arbitrary JSON objects — the service imposes no schema on the values stored, giving the frontend full flexibility over what it persists. The service also supports full backup and restore of all configs.

Org Config

An org config stores frontend settings at the organization level (e.g. theme, language, dashboard layout).

Field	Description
org_id	ID of the organization the config belongs to
config	Arbitrary JSON object containing the UI configuration settings

Thing Config

A thing config stores frontend settings for a specific thing (e.g. chart type, display unit, decimal precision).

Field	Description
thing_id	ID of the thing the config belongs to
group_id	ID of the group the thing belongs to
config	Arbitrary JSON object containing the UI configuration settings

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_UI_CONFIGS_LOG_LEVEL	Log level for the UI Configs service (debug, info, warn, error)	error
MF_UI_CONFIGS_HTTP_PORT	UI Configs service HTTP port	9029
MF_JAEGER_URL	Jaeger server URL for distributed tracing. Leave empty to disable tracing.
MF_UI_CONFIGS_DB_HOST	Database host address	localhost
MF_UI_CONFIGS_DB_PORT	Database host port	5432
MF_UI_CONFIGS_DB_USER	Database user	mainflux
MF_UI_CONFIGS_DB_PASS	Database password	mainflux
MF_UI_CONFIGS_DB	Name of the database used by the service	uiconfigs
MF_UI_CONFIGS_DB_SSL_MODE	Database connection SSL mode (disable, require, verify-ca, verify-full)	disable
MF_UI_CONFIGS_DB_SSL_CERT	Path to the PEM encoded certificate file
MF_UI_CONFIGS_DB_SSL_KEY	Path to the PEM encoded key file
MF_UI_CONFIGS_DB_SSL_ROOT_CERT	Path to the PEM encoded root certificate file
MF_UI_CONFIGS_CLIENT_TLS	Flag that indicates if TLS should be turned on	false
MF_UI_CONFIGS_CA_CERTS	Path to trusted CAs in PEM format
MF_UI_CONFIGS_SERVER_CERT	Path to server certificate in PEM format
MF_UI_CONFIGS_SERVER_KEY	Path to server key in PEM format
MF_THINGS_AUTH_GRPC_URL	Things service Auth gRPC URL	localhost:8183
MF_THINGS_AUTH_GRPC_TIMEOUT	Things service Auth gRPC request timeout in seconds	1s
MF_AUTH_GRPC_URL	Auth service gRPC URL	localhost:8181
MF_AUTH_GRPC_TIMEOUT	Auth service gRPC request timeout in seconds	1s
MF_UI_CONFIGS_ES_URL	Event store URL	redis://localhost:6379/0
MF_UI_CONFIGS_EVENT_CONSUMER	Event store consumer name	uiconfigs

Deployment

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

To start the service, execute the following shell script:

# Download the latest version of the service
git clone https://github.com/MainfluxLabs/mainflux

cd mainflux

# compile the uiconfigs service
make uiconfigs

# Copy binary to bin
make install

# Set the environment variables and run the service
MF_UI_CONFIGS_LOG_LEVEL=[UI Configs log level] \
MF_UI_CONFIGS_HTTP_PORT=[UI Configs service HTTP port] \
MF_UI_CONFIGS_DB_HOST=[Database host address] \
MF_UI_CONFIGS_DB_PORT=[Database host port] \
MF_UI_CONFIGS_DB_USER=[Database user] \
MF_UI_CONFIGS_DB_PASS=[Database password] \
MF_UI_CONFIGS_DB=[UI Configs database name] \
MF_THINGS_AUTH_GRPC_URL=[Things service Auth gRPC URL] \
MF_THINGS_AUTH_GRPC_TIMEOUT=[Things service Auth gRPC request timeout] \
MF_AUTH_GRPC_URL=[Auth service gRPC URL] \
MF_AUTH_GRPC_TIMEOUT=[Auth service gRPC request timeout] \
$GOBIN/mainfluxlabs-uiconfigs

Usage

For the full HTTP API reference, see the OpenAPI specification.

Documentation

Index

• Variables
• type Backup
• type Config
• type OrgConfig
• type OrgConfigBackup
• type OrgConfigPage
• type OrgConfigRepository
• type Service
  • func New(orgConfigs OrgConfigRepository, thingConfigs ThingConfigRepository, ...) Service
• type ThingConfig
• type ThingConfigBackup
• type ThingConfigPage
• type ThingConfigRepository

Variables

var AllowedOrders = map[string]string{
	"id":   "id",
	"name": "name",
}

Types

type Backup

type Backup struct {
	OrgsConfigs   []OrgConfig
	ThingsConfigs []ThingConfig
}

type Config

type Config map[string]any

type OrgConfig

type OrgConfig struct {
	OrgID  string
	Config Config
}

type OrgConfigBackup

type OrgConfigBackup struct {
	OrgsConfigs []OrgConfig
}

type OrgConfigPage

type OrgConfigPage struct {
	Total       uint64
	OrgsConfigs []OrgConfig
}

type OrgConfigRepository

type OrgConfigRepository interface {
	// Save creates a new organization config record in the database.
	Save(ctx context.Context, oc OrgConfig) (OrgConfig, error)

	// RetrieveByOrg returns the organization config associated with the given org ID
	RetrieveByOrg(ctx context.Context, orgID string) (OrgConfig, error)

	// RetrieveAll retrieves all organization configs.
	RetrieveAll(ctx context.Context, pm apiutil.PageMetadata) (OrgConfigPage, error)

	// Update performs an update to the existing organization config.
	Update(ctx context.Context, oc OrgConfig) (OrgConfig, error)

	// Remove removes the organization configs with the provided identifier.
	Remove(ctx context.Context, orgID string) error

	// BackupAll retrieves all org configs.
	BackupAll(ctx context.Context) (OrgConfigBackup, error)
}

type Service

type Service interface {
	// ViewOrgConfig retrieves the org config for the authenticated user and org.
	ViewOrgConfig(ctx context.Context, token, orgID string) (OrgConfig, error)

	// ListOrgsConfigs retrieves all org configs.
	ListOrgsConfigs(ctx context.Context, token string, pm apiutil.PageMetadata) (OrgConfigPage, error)

	// UpdateOrgConfig updates an existing org config for the authenticated user.
	UpdateOrgConfig(ctx context.Context, token string, orgConfig OrgConfig) (OrgConfig, error)

	// RemoveOrgConfig removes the org config by org id.
	RemoveOrgConfig(ctx context.Context, orgID string) error

	// BackupOrgsConfigs retrieves all org configs.
	BackupOrgsConfigs(ctx context.Context, token string) (OrgConfigBackup, error)

	// ViewThingConfig retrieves the thing config for the authenticated user and thing.
	ViewThingConfig(ctx context.Context, token, thingID string) (ThingConfig, error)

	// ListThingsConfigs retrieves all thing configs.
	ListThingsConfigs(ctx context.Context, token string, pm apiutil.PageMetadata) (ThingConfigPage, error)

	// UpdateThingConfig updates an existing thing config for the authenticated user.
	UpdateThingConfig(ctx context.Context, token string, thingConfig ThingConfig) (ThingConfig, error)

	// RemoveThingConfig removes the thing config by thing id.
	RemoveThingConfig(ctx context.Context, thingID string) error

	// RemoveThingConfigByGroup removes the thing config by group id.
	RemoveThingConfigByGroup(ctx context.Context, groupID string) error

	// BackupThingsConfigs retrieves all thing configs.
	BackupThingsConfigs(ctx context.Context, token string) (ThingConfigBackup, error)

	// Backup retrieves all org and thing configs.
	Backup(ctx context.Context, token string) (Backup, error)

	// Restore adds all orgs and things configs from a backup.
	Restore(ctx context.Context, token string, backup Backup) error
}

Service specifies an API that must be fullfiled by the domain service implementation, and all of its decorators (e.g. logging & metrics).

func New

func New(orgConfigs OrgConfigRepository, thingConfigs ThingConfigRepository, things domain.ThingsClient, auth domain.AuthClient, idp uuid.IDProvider, logger logger.Logger) Service

type ThingConfig

type ThingConfig struct {
	ThingID string
	GroupID string
	Config  Config
}

type ThingConfigBackup

type ThingConfigBackup struct {
	ThingsConfigs []ThingConfig
}

type ThingConfigPage

type ThingConfigPage struct {
	Total         uint64
	ThingsConfigs []ThingConfig
}

type ThingConfigRepository

type ThingConfigRepository interface {
	// Save creates a new thing config record in the database.
	Save(ctx context.Context, tc ThingConfig) (ThingConfig, error)

	// RetrieveByThing returns the thing config associated with the given thing ID.
	RetrieveByThing(ctx context.Context, thingID string) (ThingConfig, error)

	// RetrieveAll retrieves all thing configs.
	RetrieveAll(ctx context.Context, pm apiutil.PageMetadata) (ThingConfigPage, error)

	// Update performs an update to the existing thing config.
	Update(ctx context.Context, tc ThingConfig) (ThingConfig, error)

	// Remove removes the thing configs with the given thing ID.
	Remove(ctx context.Context, thingID string) error

	// RemoveByGroup deletes all thing configs that belong to the given group ID
	RemoveByGroup(ctx context.Context, groupID string) error

	// BackupAll retrieves all thing configs.
	BackupAll(ctx context.Context) (ThingConfigBackup, error)
}