install, faq, configuration: add Docker as first-class citizen

source/user/configuration.rst

@@ -2,7 +2,7 @@
 Configuration
 =============
 
-Kurento works by orchestrating a broad set of technologies that must be made to work together. Some of these technologies can accept different configuration parameters that Kurento makes available through several configuration files:
+Most (but not all, see below) of the settings in Kurento can be set statically in configuration files:
 
 * ``/etc/kurento/kurento.conf.json``
 
@@ -28,12 +28,17 @@ Kurento works by orchestrating a broad set of technologies that must be made to
 
   This file is loaded by the system's service init files. Defines some environment variables, which have an effect on features such as the *Debug Logging*, or the *Core Dump* files that are generated when a crash happens.
 
-For convenience, the :ref:`Kurento Docker <installation-docker>` also accepts some environment variables that map directly to settings in the above files. If this is not flexible enough, you can always use a `bind-mount <https://docs.docker.com/storage/bind-mounts/>`__ or `volume <https://docs.docker.com/storage/volumes/>`__ with a different set of configuration files in ``/etc/kurento/``. Of course, you can also base upon the Kurento Docker image and extend it to add your own configuration, modifications, or custom plugins, as desired.
+For other settings not directly available in configuration files, make sure to read the Client API SDK docs, where all exposed methods are documented:
+
+* `Kurento Client JavaDoc <../_static/client-javadoc/index.html>`__.
+* `Kurento Client JsDoc <../_static/client-jsdoc/index.html>`__.
+
+The :ref:`Kurento Docker <installation-docker>` images also accept some environment variables that map directly to settings in the above files. If this is not flexible enough, you can always use a `bind-mount <https://docs.docker.com/storage/bind-mounts/>`__ or `volume <https://docs.docker.com/storage/volumes/>`__ with a different set of configuration files in ``/etc/kurento/``. For some tips about these techniques, go to :ref:`faq-docker`.
 
 
 
 Debug logging
--------------
+=============
 
 KMS uses the environment variable ``GST_DEBUG`` to define the debug level of all underlying modules. Check :doc:`/features/logging` for more information about this and other environment variables.
 
@@ -56,7 +61,7 @@ Set this variable to change the verbosity level of the log messages generated by
 
 
 STUN/TURN server
-----------------
+================
 
 Read :ref:`faq-stun-needed` to learn about when you might need to use these, and :ref:`installation-stun-turn` for guidance on how to install your own STUN/TURN server.
 
@@ -76,7 +81,7 @@ Read :ref:`faq-stun-needed` to learn about when you might need to use these, and
 
 
 Network interface
------------------
+=================
 
 To specify the network interface name(s) that KMS should use to communicate from the environment where it is running (either a physical machine, a virtual machine, a Docker container, etc.)
 
@@ -96,7 +101,7 @@ To specify the network interface name(s) that KMS should use to communicate from
 
 
 RTP port
---------
+========
 
 You can configure the minimum and maximum ports that Kurento Media Server will open (bind to) in order to receive RTP packets from remote peers. This affects the operation of both RtpEndpoint and WebRtcEndpoint.
 
@@ -110,11 +115,16 @@ You can configure the minimum and maximum ports that Kurento Media Server will o
 
 
 
+Advanced settings
+=================
+
+These settings are only provided for advanced users who know what they are doing and why they need them. For most cases, it's better to leave these settings on their default values.
+
+
+
 External IP address
 -------------------
 
-Only for advanced users who know what they are doing and why they need to set this. For most cases, it's better to leave this unset and use a STUN/TURN server instead.
-
 When this feature is used, all of the Kurento IPv4 and/or IPv6 ICE candidates are mangled to contain the given address. This can speed up WebRTC connection establishment in scenarios where the external or public IP is already well known, also having the benefit that STUN won't be needed *for the media server*.
 
 **Local install**
@@ -136,7 +146,9 @@ When this feature is used, all of the Kurento IPv4 and/or IPv6 ICE candidates ar
 Maximum Transmission Unit
 -------------------------
 
-Only for advanced users who know what they are doing. For most cases, it's better to use the default MTU value of 1200 Bytes.
+The MTU is a hard limit on the size that outbound packets will have. For some users it is important being able to lower the packet size in order to prevent fragmentation.
+
+For the vast majority of use cases it is better to use the default MTU value of 1200 Bytes, which is also the default value in most popular implementations of WebRTC (see :ref:`browser-mtu`).
 
 **Local install**
 

source/user/faq.rst

@@ -281,10 +281,69 @@ When you are done, (re)start both Coturn and Kurento servers:
 
 
 
+.. _faq-docker:
+
+About using Kurento with Docker
+===============================
+
+Docker is the recommended method of deploying Kurento Media Server, because it makes it easy to bundle all of the different modules and dependencies into a single, manageable unit. This makes installation and upgrades a trivial operation. However, due to the nature of containers, it also makes configuration slightly more inconvenient, so in this section we'll provide a heads up in Docker concepts that could be very useful for users of `Kurento Docker images <https://hub.docker.com/r/kurento/kurento-media-server>`__.
+
+
+
+How to edit configuration files?
+--------------------------------
+
+If you want to provide your own configuration files to the Kurento Docker image, you can use either a Docker `bind-mount <https://docs.docker.com/storage/bind-mounts/>`__ or `volume <https://docs.docker.com/storage/volumes/>`__.
+
+However, the first thing you'll need are the actual files! You can get them with these commands:
+
+.. code-block:: console
+
+   CONTAINER="$(docker create kurento/kurento-media-server:latest)"
+   docker cp "$CONTAINER":/etc/kurento/. ./etc-kurento
+   docker rm "$CONTAINER"
+
+Now, edit the files as needed. Later, provide them to newly created containers as a bind-mount:
+
+.. code-block:: console
+
+   docker run -d --name kms --network host \
+       --mount type=bind,src="$PWD/etc-kurento",dst=/etc/kurento \
+       kurento/kurento-media-server:latest
+
+
+
+Where are my recordings?
+------------------------
+
+Running a Docker container **won't modify your host system** and **won't create new files** or anything like that, at least by default. This is part of how Docker containers work, and is important to keep in mind for certain cases.
+
+For example, when using the *RecorderEndpoint*, a common question is where the recorded files are being stored, because they don't show up anywhere in the file system. The answer is that KMS stores files *inside the container*, in the path defined by the *RecorderEndpoint* constructor (`Java <https://doc-kurento.readthedocs.io/en/latest/_static/client-javadoc/org/kurento/client/RecorderEndpoint.Builder.html#Builder-org.kurento.client.MediaPipeline-java.lang.String->`__, `JavaScript <https://doc-kurento.readthedocs.io/en/latest/_static/client-jsdoc/module-elements.RecorderEndpoint.html#.constructorParams>`__).
+
+
+
+About Kurento Media Pipelines
+=============================
+
+These questions relate to the concept of :term:`Media Pipeline` in Kurento, touching topics about architecture or performance.
+
+
+
+How many simultaneous participants are supported?
+-------------------------------------------------
+
+This depends entirely on the performance of the machine where Kurento Media Server is running. The best thing you can do to know is performing an actual load test and see it by yourself.
+
+The folks working on `OpenVidu <https://openvidu.io/>`__ (a WebRTC platform that is based on Kurento) conducted a study that you might find interesting:
+
+* `OpenVidu load testing: a systematic study of OpenVidu platform performance <https://medium.com/@openvidu/openvidu-load-testing-a-systematic-study-of-openvidu-platform-performance-b1aa3c475ba9>`__.
+
+
+
 How many Media Pipelines do I need for my Application?
-======================================================
+------------------------------------------------------
 
-A Pipeline is a top-level container that handles every resource that should be able to achieve any kind of interaction with each other. Media Elements can only communicate when they are part of the same Pipeline. Different Pipelines in the server are independent, so they do not share audio, video, data or events.
+A Pipeline is a top-level container that handles every resource that should be able to achieve any kind of interaction with each other. A :term:`Media Element` can only communicate when they are part of the same Pipeline. Different Pipelines in the server are independent and isolated, so they do not share audio, video, data or events.
 
 99% times, this translates to using 1 Pipeline object for each "room"-like videoconference. It doesn't matter if there is 1 single presenter and N viewers ("one-to-many"), or if there are N participants Skype-style ("many-to-many"), all of them are managed by the same Pipeline. So, most actual real-world applications would only ever create 1 Pipeline, because that's good enough for most needs.
 
@@ -293,13 +352,13 @@ A good heuristic is that you will need one Pipeline per each set of communicatin
 
 
 How many Endpoints do I need?
-=============================
+-----------------------------
 
 Your application will need to create at least one Endpoint for each media stream flowing to (or from) each participant. You might actually need more, if the streams are to be recorded or if streams are being duplicated for other purposes.
 
 
 
 Which participant corresponds to which Endpoint?
-================================================
+------------------------------------------------
 
 The Kurento API offers no way to get application-level semantic attributes stored in a Media Element. However, the application developer can maintain a HashMap or equivalent data structure, storing the Endpoint identifiers (which are plain strings) to whatever application information is desired, such as the names of the participants.

source/user/installation.rst

@@ -74,17 +74,13 @@ Docker image
 
 The `kurento-media-server Docker image <https://hub.docker.com/r/kurento/kurento-media-server>`__ is a nice *all-in-one* package for an easy quick start. It comes with all the default settings, which is enough to let you try the :doc:`/user/tutorials`.
 
-For *real-world* application development, developers are encouraged to `base FROM <https://docs.docker.com/engine/reference/builder/#from>`__ this Docker image and build their own, with any customizations that they need or want. That's the nice thing about how Docker containers operate, you can build your own images based on the previous work of others!
-
-Running a Docker container **won't modify your host system** and **won't create new files** or anything like that, at least by default. This is part of how Docker containers work, and is important to keep in mind for certain cases. For example, when using the `RecorderEndpoint <https://doc-kurento.readthedocs.io/en/latest/_static/client-javadoc/org/kurento/client/RecorderEndpoint.html>`__ (which creates new files in the local filesystem) some users that are new to Docker might be wondering where the recordings are stored; the answer is *inside the container*.
-
-If you need to insert or extract files from a Docker container, there is a variety of methods: You could use a `bind mount <https://docs.docker.com/storage/bind-mounts/>`__; a `volume <https://docs.docker.com/storage/volumes/>`__; `export <https://docs.docker.com/engine/reference/commandline/container_export/>`__ some files from an already existing container; change your `ENTRYPOINT <https://docs.docker.com/engine/reference/run/#entrypoint-default-command-to-execute-at-runtime>`__ to generate the files at startup; or customize this Docker image to introduce any desired changes.
+If you need to insert or extract files from a Docker container, there is a variety of methods: You could use a `bind mount <https://docs.docker.com/storage/bind-mounts/>`__; a `volume <https://docs.docker.com/storage/volumes/>`__; `cp <https://docs.docker.com/engine/reference/commandline/cp/>`__ some files from an already existing container; change your `ENTRYPOINT <https://docs.docker.com/engine/reference/run/#entrypoint-default-command-to-execute-at-runtime>`__ to generate or copy the files at startup; or `base FROM <https://docs.docker.com/engine/reference/builder/#from>`__ this Docker image and build a new one with your own customizations. Check :ref:`faq-docker` for an example of how to use bind-mounts to provide your own configuration files.
 
 These are the exact contents of the image:
 
-* A local ``apt-get`` installation of KMS, as described in :ref:`installation-local`.
+* A local ``apt-get`` installation of KMS, as described in :ref:`installation-local`, plus all its extra plugins (chroma, platedetector, etc).
 * Debug symbols installed, as described in :ref:`dev-dbg`. This allows getting useful stack traces in case the KMS process crashes. If this happens, please `report a bug <https://github.com/Kurento/bugtracker/issues>`__.
-* All **default settings** from the local installation, as found in ``/etc/kurento/``. For changing those settings, check :doc:`/user/configuration`.
+* All **default settings** from the local installation, as found in ``/etc/kurento/``. For details, see :doc:`/user/configuration`.