diff --git a/docs/services/general-info/_index.md b/docs/services/general-info/_index.md new file mode 100644 index 0000000000..f89b928d2b --- /dev/null +++ b/docs/services/general-info/_index.md @@ -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. diff --git a/docs/services/general-info/envvar-scopes.md b/docs/services/general-info/envvar-scopes.md new file mode 100644 index 0000000000..a02eca6477 --- /dev/null +++ b/docs/services/general-info/envvar-scopes.md @@ -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. diff --git a/docs/services/new-service-checklist.md b/docs/services/general-info/new-service-checklist.md similarity index 95% rename from docs/services/new-service-checklist.md rename to docs/services/general-info/new-service-checklist.md index d5a99ee648..45dbf364bd 100644 --- a/docs/services/new-service-checklist.md +++ b/docs/services/general-info/new-service-checklist.md @@ -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 `` good `` - [ ] 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` diff --git a/docs/services/port-ranges.md b/docs/services/general-info/port-ranges.md similarity index 87% rename from docs/services/port-ranges.md rename to docs/services/general-info/port-ranges.md index 7952337b39..a9daef8b34 100644 --- a/docs/services/port-ranges.md +++ b/docs/services/general-info/port-ranges.md @@ -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 | diff --git a/services/antivirus/README.md b/services/antivirus/README.md index 2ed95fc63c..875eee1482 100644 --- a/services/antivirus/README.md +++ b/services/antivirus/README.md @@ -1,4 +1,4 @@ -# Antivirus Service +# Antivirus The `antivirus` service is responsible for scanning files for viruses. diff --git a/services/audit/README.md b/services/audit/README.md index 31239cb2cb..744f51197b 100644 --- a/services/audit/README.md +++ b/services/audit/README.md @@ -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. diff --git a/services/auth-basic/README.md b/services/auth-basic/README.md index 82db24a703..c1b1db30bc 100644 --- a/services/auth-basic/README.md +++ b/services/auth-basic/README.md @@ -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. diff --git a/services/auth-bearer/README.md b/services/auth-bearer/README.md index a8ece5de95..6ada9310e3 100644 --- a/services/auth-bearer/README.md +++ b/services/auth-bearer/README.md @@ -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. diff --git a/services/eventhistory/README.md b/services/eventhistory/README.md index ff3ab09979..66b7b13594 100644 --- a/services/eventhistory/README.md +++ b/services/eventhistory/README.md @@ -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. diff --git a/services/frontend/README.md b/services/frontend/README.md index 8065bad7cf..d8597106ed 100644 --- a/services/frontend/README.md +++ b/services/frontend/README.md @@ -1,4 +1,4 @@ -# Frontend Service +# Frontend The frontend service translates various owncloud related HTTP APIs to CS3 requests. diff --git a/services/gateway/README.md b/services/gateway/README.md index fb267ad16a..bd16605b56 100644 --- a/services/gateway/README.md +++ b/services/gateway/README.md @@ -1,4 +1,4 @@ -# Gateway Service +# Gateway The gateway service is an ... diff --git a/services/graph/README.md b/services/graph/README.md index 8908121d38..0bcc40a4d3 100644 --- a/services/graph/README.md +++ b/services/graph/README.md @@ -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. diff --git a/services/idm/README.md b/services/idm/README.md index 74a43ad281..fe168f5ad4 100644 --- a/services/idm/README.md +++ b/services/idm/README.md @@ -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. diff --git a/services/idp/README.md b/services/idp/README.md index 4afef73e2c..01aefeb0ca 100644 --- a/services/idp/README.md +++ b/services/idp/README.md @@ -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. diff --git a/services/invitations/README.md b/services/invitations/README.md index f64fd8db45..ae8bd1fdc3 100644 --- a/services/invitations/README.md +++ b/services/invitations/README.md @@ -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. diff --git a/services/nats/README.md b/services/nats/README.md index 823953be1d..c72f1e599c 100644 --- a/services/nats/README.md +++ b/services/nats/README.md @@ -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. diff --git a/services/notifications/README.md b/services/notifications/README.md index 507d7afab3..51d58bc9b8 100644 --- a/services/notifications/README.md +++ b/services/notifications/README.md @@ -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. diff --git a/services/ocs/README.md b/services/ocs/README.md index 81db9da61f..12e8ff6290 100644 --- a/services/ocs/README.md +++ b/services/ocs/README.md @@ -1,4 +1,4 @@ -# OCS Service +# OCS The ocs service is an ... diff --git a/services/policies/README.md b/services/policies/README.md index dd93f6e5d2..b0911a28e3 100644 --- a/services/policies/README.md +++ b/services/policies/README.md @@ -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. diff --git a/services/postprocessing/README.md b/services/postprocessing/README.md index d5717b3431..50f35ee299 100644 --- a/services/postprocessing/README.md +++ b/services/postprocessing/README.md @@ -1,4 +1,4 @@ -# Postprocessing Service +# Postprocessing The `postprocessing` service handles the coordination of asynchronous postprocessing steps. diff --git a/services/proxy/README.md b/services/proxy/README.md index 73db853a1c..eae7359dd7 100644 --- a/services/proxy/README.md +++ b/services/proxy/README.md @@ -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. diff --git a/services/search/README.md b/services/search/README.md index fc93daf3c0..fa36b3b806 100644 --- a/services/search/README.md +++ b/services/search/README.md @@ -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_: diff --git a/services/storage-system/README.md b/services/storage-system/README.md index 5cdb8cb44a..005713cfca 100644 --- a/services/storage-system/README.md +++ b/services/storage-system/README.md @@ -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 `:/` like `10.10.0.200:26379/mymaster`. \ No newline at end of file +4. When using `redis-sentinel`, the Redis master to use is configured via `STORAGE_SYSTEM_CACHE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. diff --git a/services/storage-users/README.md b/services/storage-users/README.md index 5e36463e83..c9e1702c20 100644 --- a/services/storage-users/README.md +++ b/services/storage-users/README.md @@ -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 `:/` like `10.10.0.200:26379/mymaster`. \ No newline at end of file +4. When using `redis-sentinel`, the Redis master to use is configured via `STORAGE_SYSTEM_CACHE_NODES` in the form of `:/` like `10.10.0.200:26379/mymaster`. diff --git a/services/thumbnails/README.md b/services/thumbnails/README.md index 5592a601f8..43dbc463d0 100644 --- a/services/thumbnails/README.md +++ b/services/thumbnails/README.md @@ -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. diff --git a/services/userlog/README.md b/services/userlog/README.md index d91154e0dc..f8cc6fed93 100644 --- a/services/userlog/README.md +++ b/services/userlog/README.md @@ -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. diff --git a/services/web/README.md b/services/web/README.md index 9e2cbeadc7..cb988fec1c 100644 --- a/services/web/README.md +++ b/services/web/README.md @@ -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. diff --git a/services/webdav/README.md b/services/webdav/README.md index 72c7731237..d13656c4de 100644 --- a/services/webdav/README.md +++ b/services/webdav/README.md @@ -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. diff --git a/services/webfinger/README.md b/services/webfinger/README.md index f306e97d99..9409d21e69 100644 --- a/services/webfinger/README.md +++ b/services/webfinger/README.md @@ -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.