From 22641aacd1a2988e68b10e5ec7852a839d22d373 Mon Sep 17 00:00:00 2001 From: Noah Oblath Date: Thu, 10 Oct 2024 15:28:29 -0700 Subject: [PATCH] Documentation update --- documentation/source/authentication.rst | 68 ------------------------ documentation/source/building.rst | 14 ++--- documentation/source/configuration.rst | 32 ++++++++++- documentation/source/getting_started.rst | 16 +++--- documentation/source/index.rst | 1 - documentation/source/library.rst | 2 + 6 files changed, 46 insertions(+), 87 deletions(-) delete mode 100644 documentation/source/authentication.rst diff --git a/documentation/source/authentication.rst b/documentation/source/authentication.rst deleted file mode 100644 index ca5e6f4b..00000000 --- a/documentation/source/authentication.rst +++ /dev/null @@ -1,68 +0,0 @@ -.. _authentication: - -============== -Authentication -============== - -Broker Information -================== - -The basic information needed for communicating with the broker is the broker address and the port. -These can be specified either in the application configuration file or as command-line arguments. - -Configuration file (YAML):: - - broker: my.broker - broker-port: 5362 - -Command-line arguments:: - - --broker my.broker - --port 5762 - -If your broker is using the default port (5762), it doesn't need to be separately specified when running -any dripline applications. - -RabbitMQ Authentication ------------------------ - -Authentication for communication with the RabbitMQ broker is performed with a username/password pair. - -Authentication File -=================== - -The authentication information is typically stored in an authentication file (JSON format) -on the machine running the dripline application. -The authentication file can also store the broker address and port, -though the broker information can also be overridden with an application configuration file and -command-line arguments. - -An authentication file for dripline can look like this (JSON):: - - { - "amqp": { - "username": "a_user", - "password": "123456" - "broker": "my.broker" - "broker-port": 5762 - } - } - -The username and password are required, but the ``broker`` and ``broker-port`` are optional, -as they may be specified in the application configuraiton file or command-line arguments. - -Specifying the File -------------------- - -The default path can be set at build time by defining ``DRIPLINE_AUTH_FILE`` before building dripline-cpp -in a derived project. If that macro is not defined, then there is no default path. - -The authentication file is specified in an application configuration as: - - amqp: - auth-file: [filename] - -At runtime the authentication file path can be modified by any of the normal ways, plus the -command-line argument: - - --auth-file [file] diff --git a/documentation/source/building.rst b/documentation/source/building.rst index 80ee8966..92963e3b 100644 --- a/documentation/source/building.rst +++ b/documentation/source/building.rst @@ -25,7 +25,7 @@ Dripline build options include: if ON, builds the example applications ``Dripline_BUILD_PYTHON`` (BOOL) - if ON, builds utilities used by the Python wrapping + if ON, builds utilities used by the Python wrapping (Dripline python wrapping is done in Dripline-python) ``Dripline_ENABLE_EXECUTABLES`` (BOOL) if ON, builds the Dripline executables @@ -52,22 +52,15 @@ The CMake option and possible values are: ``Release`` only prints warning and error messages; highly optimized, and no debugging symbols included -You can additionally define preprocessor macros that are used directly in the code: - -.. glossary:: - - ``DRIPLINE_AUTH_FILE`` (PATH) - specifies the location and filename of the default authentication file - - .. _standalone-option: Standalone Option ================= In standalone mode, one compiles only the dripline-cpp repository and its dependencies. -This option is best for testing, providing access to commandline tools, or when a derrived software product uses dripline-cpp as an external dependency. +This option is best for testing, providing access to command-line tools, or when a derrived software product uses dripline-cpp as an external dependency. This is the approach used in the Dockerfile, which is included in the dripline-cpp repository and used to automatically build dripline-cpp container images. +Dripline-python's recommended build also expects dripline-cpp as an external dependency. The steps are: 1. Clone the repository:: @@ -96,7 +89,6 @@ Submodule Option The submodule build configuration is for when the dripline-cpp is being include as a git submodule in some derived package's repository. This option is best when you want to track and pin the exact dripline-cpp version to be used in another project and you want to build them together using cmake. -This is the approach used in the dripline-python package, which builds a python library on top of dripline-cpp. The steps for this mode are: 1. Go to the top-level directory of the parent pacakge in which you want to include dripline-cpp:: diff --git a/documentation/source/configuration.rst b/documentation/source/configuration.rst index 9f86be45..a84ca9e6 100644 --- a/documentation/source/configuration.rst +++ b/documentation/source/configuration.rst @@ -4,6 +4,11 @@ Configuration An application that uses the Scarab application framework, including ``dl-agent`` and ``dl-mon``, will have a global dictionary-like set of configuration parameters. +The parameters can generally be divided into two sets: + + 1. Dripline-mesh parameters, which describe the specifications of the mesh that is being used, and + 2. Application parameters, which are particular to the application being run (e.g. ``dl-agent`` or a service) + In this documentation, configurations will be indicated using YAML, and the mapping collection. In the source code, this is implemented as a ``scarab::param_node``. @@ -43,7 +48,7 @@ The defaults for all of these parameters are given in the class ``dripline_confi .. code-block:: YAML - dripline: + dripline_mesh: broker: localhost broker_port: 5672 requests_exchange: requests @@ -226,3 +231,28 @@ Here's an example configuration, shown in YAML format, where environment variabl In this case the user wants a customized broker address specified at runtime by the contents of the ``DL_PREFIX`` environment variable, and they want to specify the port with ``DL_PORT``. + +Recommended Setup +================= + +The above sections describe many ways in which Dripline applications can be configured. +For convenience to the user and ease of maintenance, we recommend the following setup: + + 1. Provide the default mesh information in a ``.dripline_mesh.yaml`` file in the user's home directory. + At a minimum, include the broker address in that file. + 2. For authentication information: + + A. For manual interactive use (e.g. using ``dl-agent``), supply the RabbitMQ login details, and + the login details for any other applications (e.g. database) with environment variables. + + B. For deployed use (e.g. Docker Swarm or Kubernetes running services) either use environment variables + or secrets files. + +Examples +======== + +The dripline-cpp integration tests provide a variety of examples of how to configure dripline-cpp applications. +These are found in the source directory ``testing/integration``. +You'll find several services started in different ways in ``docker-compose.yaml``, +and a number of ``dl-agent`` commands configured differently in ``dl-tests.sh``. + \ No newline at end of file diff --git a/documentation/source/getting_started.rst b/documentation/source/getting_started.rst index 980bff93..48e167cc 100644 --- a/documentation/source/getting_started.rst +++ b/documentation/source/getting_started.rst @@ -13,10 +13,13 @@ What's Included Requirements ============ -* CMake 3.1 -* C++11 +* CMake 3.12 +* C++17 * Boost 1.46 * rabbitmqc +* libyaml-cpp +* rapidjson +* quill (logging library) Included Packages @@ -26,10 +29,10 @@ Included Packages * `scarab `_ -Getting Dripline-cpp +Getting dripline-cpp ==================== -The Dripline-cpp repository is available on `GitHub `_. +The dripline-cpp repository is available on `GitHub `_. Dripline-cpp can either be built manually, or used from a Docker container. @@ -42,7 +45,7 @@ Images are automatically built for each tagged release, and for the ``main`` and Users can also build their own images using the provided Dockerfile or by customizing their own. -Using Dripline-cpp +Using dripline-cpp ================== See :ref:`Agent ` and :ref:`Monitor ` for instructions on using the included applications. @@ -54,4 +57,5 @@ Setting Up a Mesh ================= Instructions and examples for setting up a dripline mesh can be found -from the main `dripline documentation site `_. +from the main `dripline documentation site `_ +and in the dripline-cpp integration tests. diff --git a/documentation/source/index.rst b/documentation/source/index.rst index 59344c1a..f9a47b57 100644 --- a/documentation/source/index.rst +++ b/documentation/source/index.rst @@ -23,7 +23,6 @@ Contents: Monitor Library Configuration - Authentication Offline & No-Connection .. end of toc diff --git a/documentation/source/library.rst b/documentation/source/library.rst index 64382bd7..6cd756ca 100644 --- a/documentation/source/library.rst +++ b/documentation/source/library.rst @@ -71,6 +71,8 @@ The interface for running a service consists of three functions: * ``listen()`` (blocking) * ``stop()`` +Or you can use ``run()`` to perform the start-->listen-->stop sequence. + A service can have both synchronous and asynchronous child endpoints. With the former, requests are handled synchronously with the recieving of messages and with processing messages bound for itself. With the latter, requests are passed to the appropriate endpoint, which handles them in its own thread.