Merge pull request #6039 from owncloud/create_a_general_services_info

[docs-only] Create a General Info page plus content in services for owncloud.dev
2026-10-23 06:39:13 -04:00 · 2023-04-13 09:03:45 +02:00
commit 2205e88a36
@@ -0,0 +1,13 @@
+---
+title: Genreal Information
+date: 2023-04-12T00:00:00+00:00
+weight: 10
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/services/general-info
+geekdocFilePath: _index.md
+geekdocCollapseSection: true
+---
+
+## General Information
+
+This section provides general information valid for all services.
@@ -0,0 +1,39 @@
+---
+title: Envvar Naming Scope
+date: 2023-03-23T00:00:00+00:00
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/services/general-info
+geekdocFilePath: envvar-scopes.md
+geekdocCollapseSection: true
+---
+
+The scope of an environment variable can be derived from its name. Therefore it is important to follow the correct naming scheme to enable easy and proper identification. This is important when either:
+
+-   a new local envvar is introduced.
+-   a new global envvar is added to an existing local envvar.
+
+## Envvar Definition
+
+-   A variable that is only used in a particular service is a **local envvar**.
+-   A variable that is used in more than one service is a **global envvar**.
+-   Mandatory when used in a service, a global envvar must have a local counterpart.
+-   Variables that do not belong to any service are by definition global.
+
+## Name Scope
+
+### Local Envvars
+
+A local envvar always starts with the the service name like `POSTPROCESSING_LOG_FILE`.
+
+### Global Envvars
+
+A global envvar always starts with `OCIS_` like `OCIS_LOG_FILE`.
+
+Note that this envvar is the global version of the local example above.
+
+To get a list of global envvars used in all services, see the [Global Environment Variables](https://doc.owncloud.com/ocis/next/deployment/services/env-vars-special-scope.html#global-environment-variables) table in the ocis admin documentation.
+
+## Deprecations
+
+All environment variable types that are used in a service follow the same [deprecation rules]({{< ref "ocis/development/deprecating-variables/_index.md" >}}) independent of their scope.
@@ -1,9 +1,9 @@
 ---
 title: New Service Checklist
 date: 2023-03-23T00:00:00+00:00
-weight: 0
+weight: 20
 geekdocRepo: https://github.com/owncloud/ocis
-geekdocEditPath: edit/master/docs/services
+geekdocEditPath: edit/master/docs/services/general-info
 geekdocFilePath: new-service-checklist.md
 geekdocCollapseSection: true
 ---
@@ -23,6 +23,7 @@ Use this checklist with copy/paste in your PR - right from the beginning. It ren
    bad `<img src="https://github.com/owncloud/ocis/blob/master/services/graph/images/mermaid-graph.svg" width="500" />`  
    good `<img src="https://raw.githubusercontent.com/owncloud/ocis/master/services/graph/images/mermaid-graph.svg" width="500" />`
 - [ ] If new CLI command are introduced, that command must be described in readme.md.
+- [ ] If new global envvar is introduced, the name must start with `OCIS_`.
 - [ ] Add the service to the makefile in the ocis repo root.
 - [ ] Make the service startable for binary and individual startup:
  - For single binary add service to `ocis/pkg/runtime`
@@ -1,9 +1,9 @@
 ---
 title: Port Ranges
 date: 2018-05-02T00:00:00+00:00
-weight: 0
+weight: 20
 geekdocRepo: https://github.com/owncloud/ocis
-geekdocEditPath: edit/master/docs/services
+geekdocEditPath: edit/master/docs/services/general-info
 geekdocFilePath: port-ranges.md
 geekdocCollapseSection: true
 ---
@@ -23,42 +23,42 @@ We also suggest to use the last port in your extensions' range as a debug/metric
 | Port range | Service                                                                                |
 |------------|----------------------------------------------------------------------------------------|
 | 9000-9010  | [reserved for Infinite Scale]({{< ref "../../../ocis/_index.md" >}})                   |
-| 9100-9104  | [web]({{< ref "./web/_index.md" >}})                                                   |
+| 9100-9104  | [web]({{< ref "../web/_index.md" >}})                                                  |
 | 9105-9109  | [hello](https://github.com/owncloud/ocis-hello)                                        |
-| 9110-9114  | [ocs]({{< ref "./ocs/_index.md" >}})                                                   |
-| 9115-9119  | [webdav]({{< ref "./webdav/_index.md" >}})                                             |
-| 9120-9124  | [graph]({{< ref "./graph/_index.md" >}})                                               |
-| 9125-9129  | [policies]({{< ref "./policies/_index.md" >}})                                         |
-| 9130-9134  | [idp]({{< ref "./idp/_index.md" >}})                                                   |
+| 9110-9114  | [ocs]({{< ref "../ocs/_index.md" >}})                                                  |
+| 9115-9119  | [webdav]({{< ref "../webdav/_index.md" >}})                                            |
+| 9120-9124  | [graph]({{< ref "../graph/_index.md" >}})                                              |
+| 9125-9129  | [policies]({{< ref "../policies/_index.md" >}})                                        |
+| 9130-9134  | [idp]({{< ref "../idp/_index.md" >}})                                                  |
 | 9135-9139  | FREE (formerly used by graph-explorer)                                                 |
-| 9140-9141  | [frontend]({{< ref "./frontend/_index.md" >}})                                         |
-| 9142-9143  | [gateway]({{< ref "./gateway/_index.md" >}})                                           |
-| 9144-9145  | [users]({{< ref "./users/_index.md" >}})                                               |
-| 9146-9147  | [auth-basic]({{< ref "./auth-basic/_index.md" >}})                                     |
-| 9148-9149  | [auth-bearer]({{< ref "./auth-bearer/_index.md" >}})                                   |
-| 9150-9153  | [sharing]({{< ref "./sharing/_index.md" >}})                                           |
-| 9154-9156  | [storage-shares]({{< ref "./storage-shares/_index.md" >}})                             |
-| 9157-9159  | [storage-users]({{< ref "./storage-users/_index.md" >}})                               |
-| 9160-9162  | [groups]({{< ref "./groups/_index.md" >}})                                             |
-| 9163       | [ocdav]({{< ref "./ocdav/_index.md" >}})                                               |
-| 9164       | [groups]({{< ref "./groups/_index.md" >}})                                             |
-| 9165       | [app-provider]({{< ref "./app-provider/_index.md" >}})                                 |
-| 9166-9169  | [auth-machine]({{< ref "./auth-machine/_index.md" >}})                                 |
-| 9170-9174  | [notifications]({{< ref "./notifications/_index.md" >}})                               |
-| 9175-9179  | [storage-publiclink]({{< ref "./storage-publiclink/_index.md" >}})                     |
+| 9140-9141  | [frontend]({{< ref "../frontend/_index.md" >}})                                        |
+| 9142-9143  | [gateway]({{< ref "../gateway/_index.md" >}})                                          |
+| 9144-9145  | [users]({{< ref "../users/_index.md" >}})                                              |
+| 9146-9147  | [auth-basic]({{< ref "../auth-basic/_index.md" >}})                                    |
+| 9148-9149  | [auth-bearer]({{< ref "../auth-bearer/_index.md" >}})                                  |
+| 9150-9153  | [sharing]({{< ref "../sharing/_index.md" >}})                                          |
+| 9154-9156  | [storage-shares]({{< ref "../storage-shares/_index.md" >}})                            |
+| 9157-9159  | [storage-users]({{< ref "../storage-users/_index.md" >}})                              |
+| 9160-9162  | [groups]({{< ref "../groups/_index.md" >}})                                            |
+| 9163       | [ocdav]({{< ref "../ocdav/_index.md" >}})                                              |
+| 9164       | [groups]({{< ref "../groups/_index.md" >}})                                            |
+| 9165       | [app-provider]({{< ref "../app-provider/_index.md" >}})                                |
+| 9166-9169  | [auth-machine]({{< ref "../auth-machine/_index.md" >}})                                |
+| 9170-9174  | [notifications]({{< ref "../notifications/_index.md" >}})                              |
+| 9175-9179  | [storage-publiclink]({{< ref "../storage-publiclink/_index.md" >}})                    |
 | 9180-9184  | FREE (formerly used by accounts)                                                       |
-| 9185-9189  | [thumbnails]({{< ref "./thumbnails/_index.md" >}})                                     |
-| 9190-9194  | [settings]({{< ref "./settings/_index.md" >}})                                         |
+| 9185-9189  | [thumbnails]({{< ref "../thumbnails/_index.md" >}})                                    |
+| 9190-9194  | [settings]({{< ref "../settings/_index.md" >}})                                        |
 | 9195-9199  | FREE                                                                                   |
-| 9200-9204  | [proxy]({{< ref "./proxy/_index.md" >}})                                               |
-| 9205-9209  | [proxy]({{< ref "./proxy/_index.md" >}})                                               |
+| 9200-9204  | [proxy]({{< ref "../proxy/_index.md" >}})                                              |
+| 9205-9209  | [proxy]({{< ref "../proxy/_index.md" >}})                                              |
 | 9210-9214  | FREE                                                                                   |
-| 9215-9219  | [storage-system]({{< ref "./storage-system/_index.md" >}})                             |
-| 9220-9224  | [search]({{< ref "./search/_index.md" >}})                                             |
+| 9215-9219  | [storage-system]({{< ref "../storage-system/_index.md" >}})                            |
+| 9220-9224  | [search]({{< ref "../search/_index.md" >}})                                            |
 | 9225-9229  | FREE                                                                                   |
-| 9230-9234  | [nats]({{< ref "./nats/_index.md" >}})                                                 |
-| 9235-9239  | [idm]({{< ref "./idm/_index.md" >}})                                                   |
-| 9240-9244  | [app-registry]({{< ref "./app-registry/_index.md" >}})                                 |
+| 9230-9234  | [nats]({{< ref "../nats/_index.md" >}})                                                |
+| 9235-9239  | [idm]({{< ref "../idm/_index.md" >}})                                                  |
+| 9240-9244  | [app-registry]({{< ref "../app-registry/_index.md" >}})                                |
 | 9245-9249  | FREE                                                                                   |
 | 9250-9254  | [ocis server (runtime)](https://github.com/owncloud/ocis/tree/master/ocis/pkg/runtime) |
 | 9255-9259  | FREE                                                                                   |
@@ -102,7 +102,7 @@ We also suggest to use the last port in your extensions' range as a debug/metric
 | 9445-9449  | FREE                                                                                   |
 | 9450-9454  | FREE                                                                                   |
 | 9455-9459  | FREE                                                                                   |
-| 9460-9464  | [store]({{< ref "./store/_index.md" >}})                                               |
+| 9460-9464  | [store]({{< ref "../store/_index.md" >}})                                              |
 | 9465-9469  | FREE                                                                                   |
 | 9470-9474  | FREE                                                                                   |
 | 9475-9479  | FREE                                                                                   |
@@ -1,4 +1,4 @@
-# Antivirus Service
+# Antivirus

 The `antivirus` service is responsible for scanning files for viruses.

@@ -1,4 +1,4 @@
-# Audit service
+# Audit

 The audit service logs all events of the system as an audit log. Per default, it will be logged to standard out, but can also be configured to a file output. Supported log formats are json or a minimal human-readable format.

@@ -1,4 +1,4 @@
-# Auth-Basic Service
+# Auth-Basic

 The oCIS Auth Basic service provides basic authentication for those clients who cannot handle OpenID Connect. This should only be enabled for tests and development.

@@ -1,4 +1,4 @@
-# Auth-Bearer Service
+# Auth-Bearer

 The oCIS Auth Bearer service communicates with the configured OpenID Connect identity provider to authenticate requests. OpenID Connect is the default authentication mechanism for all clients: web, desktop and mobile. Basic auth is only used for testing and has to be explicity enabled.

@@ -1,4 +1,4 @@
-# Eventhistory Service
+# Eventhistory

 The `eventhistory` consumes all events from the configured event system like NATS, stores them and allows other services to retrieve them via an eventid.

@@ -1,4 +1,4 @@
-# Frontend Service
+# Frontend

 The frontend service translates various owncloud related HTTP APIs to CS3 requests. 

@@ -1,4 +1,4 @@
-# Gateway Service
+# Gateway

 The gateway service is an ...

@@ -1,4 +1,4 @@
-# Graph service
+# Graph

 The graph service provides the Graph API which is a RESTful web API used to access Infinite Scale resources. It is inspired by the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/use-the-api) and can be used by clients or other services or extensions.

@@ -1,4 +1,4 @@
-# Idm
+# IDM

 The IDM service provides a minimal LDAP Service, based on [Libregraph idm](https://github.com/libregraph/idm), for oCIS. It is started as part of the default configuration and serves as a central place for storing user and group information.

@@ -1,4 +1,4 @@
-# IDP Service
+# IDP

 This service provides a builtin minimal OpenID Connect provider based on
 [LibreGraph Connect (lico)](https://github.com/libregraph/lico) for oCIS.
@@ -1,4 +1,4 @@
-# Invitations Service
+# Invitations

 The invitations service provides an [Invitation Manager](https://learn.microsoft.com/en-us/graph/api/invitation-post?view=graph-rest-1.0&tabs=http) that can be used to invite external users, aka guests, to an organization.

@@ -1,4 +1,4 @@
-# Nats Service
+# Nats

 The nats service is the event broker of the system. It distributes events among all other services and enables other services to communicate asynchronous.

@@ -1,4 +1,4 @@
-# Notification service
+# Notification

 The notification service is responsible for sending emails to users informing them about events that happened. To do this it hooks into the event system and listens for certain events that the users need to be informed about.

@@ -1,4 +1,4 @@
-# OCS Service
+# OCS

 The ocs service is an ...

@@ -1,4 +1,4 @@
-# Policies Service
+# Policies

 The policies service provides a new gRPC API which can be used to check whether a requested operation is allowed or not. To do so, Open Policy Agent (OPA) is used to define the set of rules of what is permitted and what is not.

@@ -1,4 +1,4 @@
-# Postprocessing Service
+# Postprocessing

 The `postprocessing` service handles the coordination of asynchronous postprocessing steps. 

@@ -1,4 +1,4 @@
-# Proxy Service
+# Proxy

 The proxy service is an API-Gateway for the ownCloud Infinite Scale microservices. Every HTTP request goes through this service. Authentication, logging and other preprocessing of requests also happens here. Mechanisms like request rate limitting or intrusion prevention are **not** included in the proxy service and must be setup in front like with an external reverse proxy.

@@ -1,4 +1,4 @@
-# Search Service
+# Search

 The search service is responsible for metadata and content extraction, stores that data as index and makes it searchable. The following clarifies the extraction terms _metadata_ and _content_:

@@ -1,4 +1,4 @@
-# Storage-System Service
+# Storage-System

 Purpose and description to be added

@@ -15,4 +15,4 @@ The `storage-system` service caches file metadata via the configured store in `S
 1.  Note that in-memory stores are by nature not reboot persistent.
 2.  Though usually not necessary, a database name can be configured for event stores if the event store supports this. Generally not applicapable for stores of type `in-memory`, `redis` and `redis-sentinel`. These settings are blank by default which means that the standard settings of the configured store applies.
 3.  The `storage-system` service can be scaled if not using `in-memory` stores and the stores are configured identically over all instances.
-4.  When using `redis-sentinel`, the Redis master to use is configured via `STORAGE_SYSTEM_CACHE_NODES` in the form of `<sentinel-host>:<sentinel-port>/<redis-master>` like `10.10.0.200:26379/mymaster`.
+4.  When using `redis-sentinel`, the Redis master to use is configured via `STORAGE_SYSTEM_CACHE_NODES` in the form of `<sentinel-host>:<sentinel-port>/<redis-master>` like `10.10.0.200:26379/mymaster`.
@@ -1,4 +1,4 @@
-# Storage-Users Service
+# Storage-Users

 Purpose and description to be added

@@ -94,4 +94,4 @@ The `storage-users` service caches file metadata via the configured store in `ST
 1.  Note that in-memory stores are by nature not reboot persistent.
 2.  Though usually not necessary, a database name can be configured for event stores if the event store supports this. Generally not applicapable for stores of type `in-memory`, `redis` and `redis-sentinel`. These settings are blank by default which means that the standard settings of the configured store applies.
 3.  The `storage-users` service can be scaled if not using `in-memory` stores and the stores are configured identically over all instances.
-4.  When using `redis-sentinel`, the Redis master to use is configured via `STORAGE_SYSTEM_CACHE_NODES` in the form of `<sentinel-host>:<sentinel-port>/<redis-master>` like `10.10.0.200:26379/mymaster`.
+4.  When using `redis-sentinel`, the Redis master to use is configured via `STORAGE_SYSTEM_CACHE_NODES` in the form of `<sentinel-host>:<sentinel-port>/<redis-master>` like `10.10.0.200:26379/mymaster`.
@@ -1,4 +1,4 @@
-# Thumbnails Service
+# Thumbnails

 The thumbnails service provides methods to generate thumbnails for various files and resolutions based on requests. It retrieves the sources at the location where the user files are stored and saves the thumbnails where system files are stored. Those locations have defaults but can be manually defined via environment variables.

@@ -1,4 +1,4 @@
-# Userlog Service
+# Userlog

 The `userlog` service is a mediator between the `eventhistory` service and clients who want to be informed about user related events. It provides an API to retrieve those.

@@ -1,4 +1,4 @@
-# Web Service
+# Web

 The web service embeds and serves the static files for the [Infinite Scale Web Client](https://github.com/owncloud/web).  
 Note that clients will respond with a connection error if the web service is not available.
@@ -1,4 +1,4 @@
-# Webdav Service
+# Webdav

 The webdav service, like the [ocdav](https://github.com/owncloud/ocis/tree/master/services/ocdav) service, provides a HTTP API following the webdav protocol. It receives HTTP calls from requestors like clients and issues gRPC calls to other services executing these requests. After the called service has finished the request, the webdav service will render their responses in `xml` and sends them back to the requestor.

@@ -1,4 +1,4 @@
-# Webfinger Service
+# Webfinger

 The webfinger service provides an RFC7033 WebFinger lookup of ownCloud instances relevant for a given user account via endpoints a the /.well-known/webfinger implementation.