Merge pull request #158 from owncloud/small_fixes

Remove run and kill command

modules/ROOT/pages/deployment/binary/binary-setup.adoc

@@ -72,7 +72,7 @@ or
 
 [source,bash]
 ----
-ocis help
+ocis --help
 ----
 
 == Accessing the Infinite Scale Runtime

modules/ROOT/pages/deployment/container/container-setup.adoc

@@ -133,9 +133,9 @@ latest
 First check the current version of the image used with the command above and compare it with the versions available on {docker-ocis-url}[Docker Hub]. When a new image is available use these steps to upgrade the image:
 
 * xref:stop-a-running-container[Stop] the running Infinite Scale container
-* xref:remove-an-ocis-image[Remove] the actual image
-* xref:download-the-ocis-image[Download] the desired new image
-* xref:start-the-ocis-runtime[Start] the Infinite Scale runtime
+* xref:remove-an-infinite-scale-image[Remove] the actual image
+* xref:download-the-infinite-scale-image[Download] the desired new image
+* xref:start-the-infinite-scale-runtime[Start] the Infinite Scale runtime
 
 For detailed commands see the corresponding sections.
 
@@ -252,7 +252,7 @@ docker run \
     owncloud/ocis
 ----
 
-To access Infinite Scale, open your browser and type `\https://<your-hostname>:9200`.
+To access Infinite Scale, open your browser and type `\https://<your-hostname>:9200`
 
 WARNING: While this is not used in production and for testing purposes only, you could run more than one Infinite Scale runtime container concurrently. In such a case, you have to define different ports and data paths for each of the runtime containers to avoid unexpected behavior.
 

modules/ROOT/pages/deployment/extensions/extension_rules.adoc

@@ -0,0 +1,68 @@
+= Extension Rules
+:toc: right
+
+:description: This document describes how concurrencies are handled with go/Infinite Scale, how this impacts instantiation of extensions and how configuration of an extension works.
+
+== Introduction
+
+{description}
+
+== Instantiation of Extensions
+
+Extensions get connected by a user or process. Due to the nature of 
+image:deployment/extensions/go_logo_blue.svg[width=40], the programming language used for Infinite Scale, each connection will create a thread which will be terminated when the connection ends. This means that as long as you have sufficient resources regarding CPU and memory, there will be as many threads created by extensions as necessary and terminated accordingly. All extensions started on the server share the same resource pool.
+
+In the image below the extensions used are just examples. It could be one extension or many extensions running concurrently. The image illustrates the following: 
+
+* As long you have resources available, the running extensions will create and terminate threads automatically.
+* There is no need to instantiate an extension on the same server to balance load.
+* If you increase the resource pool on the server, you can:
+** have more connections for existing extensions,
+** run additional but *different* extensions.
+* If the resource pool reaches its limits, you can create additional instances of extensions on a *different* server.
+* There are only a few exceptions like storage connectors as they will have a different configuration for each type of storage.
+
+These statements are true when using the runtime as well as when running extensions independent of the runtime.
+
+image::deployment/extensions/concurrence.drawio.svg[width=600]
+
+== Runtime Extensions
+
+* With the command `ocis server`, all extensions are started with the runtime and share the same PID. If you want to exclude extensions from starting with the runtime, you must define with an environment variable all extension to be started. Those not named will _not_ be started:
++
+[source,bash]
+----
+OCIS_RUN_EXTENSIONS=settings,storage-system, \
+    graph,graph-explorer,idp,ocs,store,thumbnails, \
+    web,webdav,frontend,gateway,users, groups, \
+    auth-basic,auth-bearer,storage-authmachine, \
+    storage-users,storage-shares,storage-publiclink, \
+    app-provider,sharing,proxy,ocdav \
+    ocis server
+----
++
+This is useful if you want to try starting an extension outside the runtime, e.g. when testing orchestration.
+
+* Runtime extension rules
+** You cannot instantiate a runtime extension
+** All runtime extensions are a part of the `ocis server` process and therefore share the same process ID (PID).
+** Runtime extensions share the same PID while nonruntime extensions have their own PID.
+
+== Configuration Rules
+
+Note that in the examples described, only the webdav extension is used, but the process is valid for all extensions available.
+
+Example::
+You start the Infinite Scale runtime with `ocis server`
++
+--
+. The configuration file `/etc/ocis/ocis.yaml` is read.
+. The configuration file `/etc/ocis/webdav.yaml` is read AND applied.
+. The environment variables are read and applied. These can overwrite already existing configuration elements. See section xref:deployment/general/general-info.adoc#configuration-of-infinite-scale[Configuration of Infinite Scale] about the order in which different configurations get applied (config arithmetics).
+--
++
+All extensions have started, share the same PID and have a defined config. Typing `ocis list` shows all active runtime extensions.
+
+This image gives you a graphical representation of the rule set described above.
+
+image::deployment/extensions/runtime_c1.drawio.svg[width=600]

modules/ROOT/pages/deployment/general/general-info.adoc

@@ -79,74 +79,44 @@ This will print an output like:
 
 == Managing Extensions
 
-Extensions are microservices which can be started, stopped or instantiated. Because there is a difference between extensions which are part of the runtime and extensions outside the runtime, an in-depth documentation as been added to explain some background. Please read carefully to avoid unwanted behavior. For details see the xref:deployment/extensions/extensions.adoc[Extensions] documentation.
+Extensions are microservices which can be started, stopped or instantiated. An xref:deployment/extensions/extension_rules.adoc[Extension Rules] documentation as been added to explain some background. Please read this carefully to avoid unwanted behavior. For details of each extension see the xref:deployment/extensions/extensions.adoc[Extensions] documentation.
 
 === List Available Extensions
 
-Type `ocis help` to get a list of available extensions.
+Just type `ocis` to get a list of commands and available extensions.
+
+When typing `ocis <extension-name> --help`, you will get detailed help regarding the specified extension.
 
 === Manage Instances of Extensions
 
 ==== Infinite Scale Supervised Extensions
 
-You can start, list or kill available extensions in supervised mode with the `ocis` command. _These extensions share the same PID_. To manage supervised extensions, you need to run `ocis server` first or an xref:default-runtime-error-response[error] will be thrown.
-
-[NOTE]
-====
-When an extension runs supervised, is killed and started again, the only way to provide or overwrite configuration values will be through an *extension config file*. This is because the parent process has already started in its own environment with the configuration already loaded. See the example below:
+You can start all available extensions in supervised mode with the command below. Note that the extensions started with the runtime share the same PID.
 
-// fixme: the config option was available in 1.9 but all config options were killed somewhere in march 2022. now there is a pr to implement it again, see: https://github.com/owncloud/ocis/issues/3506
+Start the Infinite Scale Runtime::
 
 [source,bash]
 ----
-ocis run proxy --config-file=/path/proxy.yaml
+ocis server
 ----
-====
-
-NOTE: This configuration file must contain *ALL* configuration details for this extension. See the xref:configuration-rules[Configuration Arithmetic] for more details. 
-
-// fixme: tell the reason, it uses the same PID...
-// Because its part of the ocis process. Added a little above.
 
 List running extensions::
-[source,bash]
-----
-ocis list
-----
 
-Kill a running extension::
 [source,bash]
 ----
-ocis kill [extension name]
-----
-
-Start an extension::
-[source,bash]
-----
-ocis run [extension name]
+ocis list
 ----
 
 ==== Unsupervised Extensions
 
-At any time, you can create unsupervised instances of an extension with `ocis [extension name]`, for example `ocis proxy`. _These extensions are independent of extensions in supervised mode and have their own PID_. The Instances are managed with classical OS methods or e.g. via Kubernetes.
+At any time, you can create unsupervised instances of an extension with `ocis [extension-name] server`, for example `ocis proxy server`. _These extensions are independent of extensions in supervised mode and have their own PID_. The Instances are managed with classic OS methods or e.g. via Kubernetes.
 
 Note that you need configuration for and access to the extension instances like with a load balancer when you scale.
 
 === Configuring Extensions
 
 To configure extensions, see the section xref:deployment/extensions/extensions.adoc[Extensions] in the _Deployment_ documentation.
 
-== Default Runtime Error Response
-
-If you have not started up `ocis server` but try to file a runtime command except `run` and `version`, a default error message like the following will be printed:
-
-[source,plaintext]
-----
-Failed to connect to the runtime. Has the runtime been started and did you configure the right runtime address (localhost:9250)?
-----
-
-To fix this, start the runtime with `ocis server` first and redo the command.
-
 == Configuration Rules
 
 // taken from: https://owncloud.dev/ocis/config/