mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-01-05 19:59:37 -06:00
Merge branch 'master' into config-doc-descriptions
This commit is contained in:
Willy Kloucek
1
docs/services/settings/.gitignore
vendored
Normal file
1
docs/services/settings/.gitignore
vendored
Normal file
@@ -0,0 +1 @@
|
||||
grpc.md
|
||||
51
docs/services/settings/_index.md
Normal file
51
docs/services/settings/_index.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: "Settings"
|
||||
date: 2018-05-02T00:00:00+00:00
|
||||
weight: 20
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/services/settings
|
||||
geekdocFilePath: _index.md
|
||||
geekdocCollapseSection: true
|
||||
---
|
||||
|
||||
## Abstract
|
||||
|
||||
When using oCIS, the requirement to store settings arises. This extension provides functionality
|
||||
for other extensions to register new settings within oCIS. It is responsible for storing the respective
|
||||
settings values as well.
|
||||
|
||||
For ease of use, this extension provides an ocis-web extension which allows users to change their settings values.
|
||||
Please refer to the [ocis-web extension docs]({{< ref "../../ocis/development/extensions/#external-ownCloud-Web-apps" >}})
|
||||
for running ocis-web extensions.
|
||||
|
||||
{{< mermaid class="text-center">}}
|
||||
graph TD
|
||||
subgraph ow[ocis-web]
|
||||
ows[ocis-web-settings]
|
||||
owc[ocis-web-core]
|
||||
end
|
||||
ows ---|"listSettingsBundles(),<br>saveSettingsValue(value)"| os[ocis-settings]
|
||||
owc ---|"listSettingsValues()"| sdk[oC SDK]
|
||||
sdk --- sdks{ocis-settings<br>available?}
|
||||
sdks ---|"yes"| os
|
||||
sdks ---|"no"| defaults[Use set of<br>default values]
|
||||
oa[oCIS extensions<br>e.g. ocis-accounts] ---|"saveSettingsBundle(bundle)"| os
|
||||
{{< /mermaid >}}
|
||||
|
||||
The diagram shows how the settings service integrates into oCIS:
|
||||
|
||||
**Settings management:**
|
||||
- oCIS extensions can register *settings bundles* with the ocis-settings service.
|
||||
- The settings frontend can be plugged into ocis-web, showing forms for changing *settings values* as a user.
|
||||
The forms are generated from the registered *settings bundles*.
|
||||
|
||||
**Settings usage:**
|
||||
- Extensions can query ocis-settings for *settings values* of a user.
|
||||
- The ownCloud SDK, used as a data abstraction layer for ocis-web, will query ocis-settings for *settings values* of a user,
|
||||
if it's available. The SDK uses sensible defaults when ocis-settings is not part of the setup.
|
||||
|
||||
For compatibility with ownCloud 10, a migration of ownCloud 10 settings into the storage of ocis-settings will be available.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
{{< toc-tree >}}
|
||||
75
docs/services/settings/bundles.md
Normal file
75
docs/services/settings/bundles.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: "Settings Bundles"
|
||||
date: 2020-05-04T00:00:00+00:00
|
||||
weight: 50
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/services/settings
|
||||
geekdocFilePath: bundles.md
|
||||
---
|
||||
|
||||
A **Settings Bundle** is a collection of settings, uniquely identified by the key of the
|
||||
extension registering the bundle and the key of the bundle itself. Its purpose is to let
|
||||
oCIS extensions define settings and make them available to users. They are dynamically
|
||||
rendered into forms, available in the frontend.
|
||||
|
||||
As of now we support five different types of settings:
|
||||
- boolean
|
||||
- integer
|
||||
- string
|
||||
- single choice list of integers or strings
|
||||
- multiple choice list of integers or strings
|
||||
|
||||
Each **Setting** is uniquely identified by a key within the bundle. Some attributes
|
||||
depend on the chosen type of setting. Through the information provided with the
|
||||
attributes of the setting, the settings frontend dynamically renders form elements,
|
||||
allowing users to change their settings individually.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
{
|
||||
"identifier": {
|
||||
"extension": "ocis-accounts",
|
||||
"bundleKey": "profile"
|
||||
},
|
||||
"displayName": "Profile",
|
||||
"settings": [
|
||||
{
|
||||
"settingKey": "lastname",
|
||||
"displayName": "Lastname",
|
||||
"description": "Input for lastname",
|
||||
"stringValue": {
|
||||
"placeholder": "Set lastname"
|
||||
}
|
||||
},
|
||||
{
|
||||
"settingKey": "age",
|
||||
"displayName": "Age",
|
||||
"description": "Input for age",
|
||||
"intValue": {
|
||||
"min": "16",
|
||||
"max": "200",
|
||||
"step": "2",
|
||||
"placeholder": "Set age"
|
||||
}
|
||||
},
|
||||
{
|
||||
"settingKey": "timezone",
|
||||
"displayName": "Timezone",
|
||||
"description": "User timezone",
|
||||
"singleChoiceValue": {
|
||||
"options": [
|
||||
{
|
||||
"stringValue": "Europe/Berlin",
|
||||
"displayValue": "Europe/Berlin"
|
||||
},
|
||||
{
|
||||
"stringValue": "Asia/Kathmandu",
|
||||
"displayValue": "Asia/Kathmandu"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
15
docs/services/settings/configuration.md
Normal file
15
docs/services/settings/configuration.md
Normal file
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Service Configuration
|
||||
date: 2018-05-02T00:00:00+00:00
|
||||
weight: 20
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/services/settings
|
||||
geekdocFilePath: configuration.md
|
||||
geekdocCollapseSection: true
|
||||
---
|
||||
|
||||
## Example YAML Config
|
||||
|
||||
{{< include file="services/_includes/settings-config-example.yaml" language="yaml" >}}
|
||||
|
||||
{{< include file="services/_includes/settings_configvars.md" >}}
|
||||
42
docs/services/settings/glossary.md
Normal file
42
docs/services/settings/glossary.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: "Glossary"
|
||||
date: 2020-05-04T12:35:00+01:00
|
||||
weight: 80
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/services/settings
|
||||
geekdocFilePath: glossary.md
|
||||
---
|
||||
|
||||
In the context of this extension and oCIS in general, we are using the following terminology.
|
||||
|
||||
### Configuration
|
||||
|
||||
- System configuration
|
||||
- e.g. service host names and ports
|
||||
- Changes need to be propagated to other services
|
||||
- Typically modified on the CLI
|
||||
|
||||
### Settings
|
||||
|
||||
- Application level settings
|
||||
- e.g. default language
|
||||
- Can be modified at runtime without restarting the service
|
||||
- Typically modified in the UI
|
||||
|
||||
### Preferences
|
||||
|
||||
- User settings
|
||||
- Subset of "Settings"
|
||||
- e.g. preferred language of a user
|
||||
|
||||
### Settings Bundle
|
||||
|
||||
- Collection of related settings
|
||||
- Registered by an oCIS extension
|
||||
|
||||
### Settings Value
|
||||
|
||||
- Manifestation of a setting for a specific user
|
||||
- E.g. used for customization (at runtime) in `ocis-web`
|
||||
- `ocis-web-settings` extension for modifying settings values is provided by this service
|
||||
- Can be queried and modified by other oCIS extensions
|
||||
22
docs/services/settings/releasing.md
Normal file
22
docs/services/settings/releasing.md
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "Releasing"
|
||||
weight: 70
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/services/settings
|
||||
geekdocFilePath: releasing.md
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Requirements
|
||||
|
||||
You need a working installation of [the Go programming language](https://golang.org/), [the Node runtime](https://nodejs.org/) and [the Yarn package manager](https://yarnpkg.com/) installed to build the assets for a working release.
|
||||
|
||||
## Releasing
|
||||
|
||||
The settings service doesn't have a dedicated release process. Simply commit your changes, make sure linting and unit tests pass locally and open a pull request.
|
||||
|
||||
### Package Hierarchy
|
||||
|
||||
- [ocis](https://github.com/owncloud/ocis)
|
||||
- [ocis-settings](https://github.com/owncloud/ocis/tree/master/settings)
|
||||
76
docs/services/settings/tests.md
Normal file
76
docs/services/settings/tests.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: "Tests"
|
||||
weight: 90
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/services/settings
|
||||
geekdocFilePath: tests.md
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
## Requirements
|
||||
|
||||
You need a working installation of [the Go programming language](https://golang.org/), [the Node runtime](https://nodejs.org/) and [the Yarn package manager](https://yarnpkg.com/) installed to run the acceptance tests. You may also want to use [Docker](https://www.docker.com/) to start the necessary services in their respective containers.
|
||||
|
||||
## Acceptance Tests
|
||||
|
||||
Make sure you've cloned the [web frontend repo](https://github.com/owncloud/web/) and the [infinite scale repo](https://github.com/owncloud/ocis/) next to each other. If your file/folder structure is different, you'll have to change the paths below accordingly.
|
||||
|
||||
### In the web repo
|
||||
|
||||
#### **Optional:** Build web to test local changes
|
||||
|
||||
Install dependencies and bundle the frontend with a watcher by running
|
||||
|
||||
```bash
|
||||
yarn && yarn build:w
|
||||
```
|
||||
|
||||
If you skip the step above, the currently bundled frontend from the oCIS binary will be used.
|
||||
|
||||
#### Dockerized acceptance test services
|
||||
|
||||
Start the necessary acceptance test services by using Docker (Compose):
|
||||
|
||||
```bash
|
||||
docker compose up selenium middleware-ocis vnc
|
||||
```
|
||||
|
||||
### In the oCIS repo
|
||||
|
||||
#### **Optional:** Build settings UI to test local changes
|
||||
|
||||
Navigate into the settings service via `cd ../settings/` and install dependencies and build the bundled settings UI with a watcher by running
|
||||
|
||||
```bash
|
||||
yarn && yarn watch
|
||||
```
|
||||
|
||||
#### Start oCIS from binary
|
||||
|
||||
Navigate into the oCIS directory inside the oCIS repository and build the oCIS binary by running
|
||||
|
||||
```bash
|
||||
make clean build
|
||||
```
|
||||
|
||||
Then, start oCIS from the binary via
|
||||
|
||||
```bash
|
||||
ocis init
|
||||
OCIS_URL=https://host.docker.internal:9200 OCIS_INSECURE=true PROXY_ENABLE_BASIC_AUTH=true WEB_UI_CONFIG=../../web/dev/docker/ocis.web.config.json ./bin/ocis server
|
||||
```
|
||||
|
||||
If you've built the web bundle locally in its repository, you also need to reference the bundle output in the above command: `WEB_ASSET_PATH=../../web/dist`
|
||||
|
||||
If you've built the settings UI bundle locally, you also need to reference the bundle output in the above command: `SETTINGS_ASSET_PATH=../settings/assets/`
|
||||
|
||||
#### Run settings acceptance tests
|
||||
|
||||
If you want visual feedback on the test run, visit http://host.docker.internal:6080/ in your browser and connect to the VNC client.
|
||||
|
||||
Navigate into the settings service via `cd ../settings/` and start the acceptance tests by running
|
||||
|
||||
```bash
|
||||
SERVER_HOST=https://host.docker.internal:9200 BACKEND_HOST=https://host.docker.internal:9200 RUN_ON_OCIS=true NODE_TLS_REJECT_UNAUTHORIZED=0 WEB_PATH=../../web WEB_UI_CONFIG=../../web/tests/drone/config-ocis.json MIDDLEWARE_HOST=http://host.docker.internal:3000 ./ui/tests/run-acceptance-test.sh ./ui/tests/acceptance/features/
|
||||
```
|
||||
75
docs/services/settings/values.md
Normal file
75
docs/services/settings/values.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: "Settings Values"
|
||||
date: 2020-05-04T00:00:00+00:00
|
||||
weight: 51
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/services/settings
|
||||
geekdocFilePath: values.md
|
||||
---
|
||||
|
||||
A **Settings Value** is the value an authenticated user has chosen for a specific setting, defined in a
|
||||
*settings bundle*. For choosing settings values as a user the sole entry point is the ocis-web extension
|
||||
provided by this service.
|
||||
|
||||
## Identifying settings values
|
||||
|
||||
A *settings value* is uniquely identified by four attributes. Three of them are coming from the definition of
|
||||
the setting within it's settings bundle (see [Settings Bundles]({{< ref "bundles" >}})
|
||||
for an example). The fourth identifies the user.
|
||||
- extension: Key of the extension that registered the settings bundle,
|
||||
- bundleKey: Key of the settings bundle,
|
||||
- settingKey: Key of the setting as defined within the bundle,
|
||||
- accountUuid: The UUID of the authenticated user who has saved the setting.
|
||||
|
||||
{{< hint info >}}
|
||||
When requests are going through `ocis-proxy`, the accountUuid attribute can be set to the static keyword `me`
|
||||
instead of using a real UUID. `ocis-proxy` will take care of minting the UUID of the authenticated user into
|
||||
a JWT, providing it in the HTTP header as `x-access-token`. That UUID is then used in this service, to replace
|
||||
`me` with the actual UUID of the authenticated user.
|
||||
{{< /hint >}}
|
||||
|
||||
## Example of stored settings values
|
||||
|
||||
```json
|
||||
{
|
||||
"values": {
|
||||
"language": {
|
||||
"identifier": {
|
||||
"extension": "ocis-accounts",
|
||||
"bundleKey": "profile",
|
||||
"settingKey": "language",
|
||||
"accountUuid": "5681371f-4a6e-43bc-8bb5-9c9237fa9c58"
|
||||
},
|
||||
"listValue": {
|
||||
"values": [
|
||||
{
|
||||
"stringValue": "de"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"timezone": {
|
||||
"identifier": {
|
||||
"extension": "ocis-accounts",
|
||||
"bundleKey": "profile",
|
||||
"settingKey": "timezone",
|
||||
"accountUuid": "5681371f-4a6e-43bc-8bb5-9c9237fa9c58"
|
||||
},
|
||||
"listValue": {
|
||||
"values": [
|
||||
{
|
||||
"stringValue": "Europe/Berlin"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## gRPC endpoints
|
||||
The obvious way of modifying settings is the ocis-web extension, as described earlier. However, services can
|
||||
use the respective gRPC endpoints of the `ValueService` to query and modify *settings values* as well.
|
||||
The gRPC endpoints require the same identifier attributes as described above, so for making a request to
|
||||
the `ValueService` you will have to make sure that the accountUuid of the authenticated user is available in
|
||||
your service at the time of the request.
|
||||
Reference in New Issue
Block a user