From 9a5714a26ff7c307abe33008b8b17bbdfdfaaf55 Mon Sep 17 00:00:00 2001 From: Martin Date: Tue, 7 Feb 2023 11:21:00 +0100 Subject: [PATCH] [docs-only] Replace the legacy Extensions with Services (#5518) * Replace the legacy Extensions with Services * Update docs/ocis/_index.md Co-authored-by: Michael Barz --------- Co-authored-by: Michael Barz --- docs/_index.md | 2 +- docs/ocis/_index.md | 8 ++++---- docs/ocis/deployment/basic-remote-setup.md | 2 +- docs/ocis/deployment/monitoring-tracing.md | 2 +- docs/ocis/getting-started/_index.md | 2 +- docs/services/port-ranges.md | 2 +- docs/services/settings/_index.md | 4 ++-- docs/services/settings/bundles.md | 2 +- docs/services/settings/glossary.md | 2 +- 9 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/_index.md b/docs/_index.md index 0b17d6b78e..80963f28b6 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -9,7 +9,7 @@ title: ownCloud Welcome to our developer documentation. Here you can find developer documentation on: - [oCIS]({{< ref "./ocis" >}}) server -- oCIS extensions +- oCIS Services - Clients like: - [ownCloud Web](https://github.com/owncloud/web) - the new web frontend for oCIS and ownCloud - [ownCloud Android app](https://github.com/owncloud/android) diff --git a/docs/ocis/_index.md b/docs/ocis/_index.md index dbfcd1e30b..a30c05676c 100644 --- a/docs/ocis/_index.md +++ b/docs/ocis/_index.md @@ -35,18 +35,18 @@ When Marie enters that URL she will be presented with a login form on the `https ### oCIS microservice runtime -The oCIS runtime allows us to dynamically manage services running in a single process. We use [suture](https://github.com/thejerf/suture) to create a supervisor tree that starts each service in a dedicated goroutine. By default oCIS will start all built-in oCIS extensions in a single process. Individual services can be moved to other nodes to scale-out and meet specific performance requirements. A [go-micro](https://github.com/asim/go-micro/blob/master/registry/registry.go) based registry allows services in multiple nodes to form a distributed microservice architecture. +The oCIS runtime allows us to dynamically manage services running in a single process. We use [suture](https://github.com/thejerf/suture) to create a supervisor tree that starts each service in a dedicated goroutine. By default oCIS will start all built-in oCIS services in a single process. Individual services can be moved to other nodes to scale-out and meet specific performance requirements. A [go-micro](https://github.com/asim/go-micro/blob/master/registry/registry.go) based registry allows services in multiple nodes to form a distributed microservice architecture. -### oCIS extensions +### oCIS Services -Every oCIS extension uses [ocis-pkg](https://github.com/owncloud/ocis/tree/master/ocis-pkg), which implements the [go-micro](https://go-micro.dev/) interfaces for [servers](https://github.com/asim/go-micro/blob/v3.5.0/server/server.go#L17-L37) to register and [clients](https://github.com/asim/go-micro/blob/v3.5.0/client/client.go#L11-L23) to lookup nodes with a service [registry](https://github.com/asim/go-micro/blob/v3.5.0/registry/registry.go). +Every oCIS service uses [ocis-pkg](https://github.com/owncloud/ocis/tree/master/ocis-pkg), which implements the [go-micro](https://go-micro.dev/) interfaces for [servers](https://github.com/asim/go-micro/blob/v3.5.0/server/server.go#L17-L37) to register and [clients](https://github.com/asim/go-micro/blob/v3.5.0/client/client.go#L11-L23) to lookup nodes with a service [registry](https://github.com/asim/go-micro/blob/v3.5.0/registry/registry.go). We are following the [12 Factor](https://12factor.net/) methodology with oCIS. The uniformity of services also allows us to use the same command, logging and configuration mechanism. Configurations are forwarded from the oCIS runtime to the individual extensions. ### go-micro -While the [go-micro](https://go-micro.dev/) framework provides abstractions as well as implementations for the different components in a microservice architecture, it uses a more developer focused runtime philosophy: It is used to download services from a repo, compile them on the fly and start them as individual processes. For oCIS we decided to use a more admin friendly runtime: You can download a single binary and start the contained oCIS extensions with a single `bin/ocis server`. This also makes packaging easier. +While the [go-micro](https://go-micro.dev/) framework provides abstractions as well as implementations for the different components in a microservice architecture, it uses a more developer focused runtime philosophy: It is used to download services from a repo, compile them on the fly and start them as individual processes. For oCIS we decided to use a more admin friendly runtime: You can download a single binary and start the contained oCIS services with a single `bin/ocis server`. This also makes packaging easier. We use [ocis-pkg](https://github.com/owncloud/ocis/tree/master/ocis-pkg) to configure the default implementations for the go-micro [grpc server](https://github.com/asim/go-micro/tree/v3.5.0/plugins/server/grpc), [client](https://github.com/asim/go-micro/tree/v3.5.0/plugins/client/grpc) and [mdns registry](https://github.com/asim/go-micro/blob/v3.5.0/registry/mdns_registry.go), swapping them out as needed, e.g. to use the [kubernetes registry plugin](https://github.com/asim/go-micro/tree/v3.5.0/plugins/registry/kubernetes). diff --git a/docs/ocis/deployment/basic-remote-setup.md b/docs/ocis/deployment/basic-remote-setup.md index 47734c8d2c..e9927600e9 100644 --- a/docs/ocis/deployment/basic-remote-setup.md +++ b/docs/ocis/deployment/basic-remote-setup.md @@ -47,7 +47,7 @@ PROXY_TRANSPORT_TLS_CERT=./certs/your-host.crt \ If you generated these certificates on your own, you might need to set `OCIS_INSECURE` to `true`. -For more configuration options check the configuration section in [oCIS]({{< ref "../config" >}}) and the oCIS extensions. +For more configuration options check the configuration section in [oCIS]({{< ref "../config" >}}) and the oCIS services. ## Start the oCIS fullstack server with Docker Compose diff --git a/docs/ocis/deployment/monitoring-tracing.md b/docs/ocis/deployment/monitoring-tracing.md index 5de3c1b6b1..83c6241e24 100644 --- a/docs/ocis/deployment/monitoring-tracing.md +++ b/docs/ocis/deployment/monitoring-tracing.md @@ -25,7 +25,7 @@ We assume that you already have oCIS deployed on one or multiple servers by usin Telegraf will collect host metrics (CPU, RAM, network, processes, ...) and docker metrics (per container CPU, RAM, network, ...). Telegraf is also configured to scrape metrics from Prometheus metric endpoints which oCIS exposes, this is done by the Prometheus input plugin . The metrics from oCIS and all other metrics gathered will be exposed with the Prometheus output plugin and can therefore be scraped by our monitoring & tracing server. -Jaeger agent is being configured as target for traces in oCIS. It then will receive traces from all oCIS extensions, add some process tags to them and forward them to our Jaeger collector on our monitoring & tracing server. +Jaeger agent is being configured as target for traces in oCIS. It then will receive traces from all oCIS services, add some process tags to them and forward them to our Jaeger collector on our monitoring & tracing server. For more information and how to deploy it, see [monitoring & tracing client](https://github.com/owncloud-devops/monitoring-tracing-client). diff --git a/docs/ocis/getting-started/_index.md b/docs/ocis/getting-started/_index.md index a7c8898871..6cee1db210 100644 --- a/docs/ocis/getting-started/_index.md +++ b/docs/ocis/getting-started/_index.md @@ -114,7 +114,7 @@ To start oCIS server: ocis server {{< / highlight >}} -The list command prints all running oCIS extensions. +The list command prints all running oCIS services. {{< highlight txt >}} ocis list {{< / highlight >}} diff --git a/docs/services/port-ranges.md b/docs/services/port-ranges.md index 2ffeaba0d6..4a9e8128f8 100644 --- a/docs/services/port-ranges.md +++ b/docs/services/port-ranges.md @@ -8,7 +8,7 @@ geekdocFilePath: port-ranges.go geekdocCollapseSection: true --- -oCIS extensions often need a port to expose their services to other services or the outside world. +oCIS services often need a port to expose their services to other services or the outside world. As users may have many different extensions running on the same machine, we should track port usage in the oCIS ecosystem. In the best case we ensure that each extension uses a non colliding port range, to make life of users easier. This page tracks the knowingly used port ranges. diff --git a/docs/services/settings/_index.md b/docs/services/settings/_index.md index 6c45e23b73..3c65759896 100644 --- a/docs/services/settings/_index.md +++ b/docs/services/settings/_index.md @@ -21,13 +21,13 @@ graph TD sdk --- sdks{ocis-settings
available?} sdks ---|"yes"| os sdks ---|"no"| defaults[Use set of
default values] - oa[oCIS extensions
e.g. ocis-accounts] ---|"saveSettingsBundle(bundle)"| os + oa[oCIS services
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. +- oCIS services can register *settings bundles* with the ocis-settings service. **Settings usage:** - Extensions can query ocis-settings for *settings values* of a user. diff --git a/docs/services/settings/bundles.md b/docs/services/settings/bundles.md index e9cd6137f9..6771d4a9ee 100644 --- a/docs/services/settings/bundles.md +++ b/docs/services/settings/bundles.md @@ -9,7 +9,7 @@ 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 +oCIS services 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: diff --git a/docs/services/settings/glossary.md b/docs/services/settings/glossary.md index bd964f42b7..c849b8a080 100644 --- a/docs/services/settings/glossary.md +++ b/docs/services/settings/glossary.md @@ -37,4 +37,4 @@ In the context of this extension and oCIS in general, we are using the following - Manifestation of a setting for a specific user - E.g. used for customization (at runtime) in `ocis-web` -- Can be queried and modified by other oCIS extensions +- Can be queried and modified by other oCIS services