From fcc047512640ac924c9c843966a32f5b502b4e61 Mon Sep 17 00:00:00 2001 From: Andrey Borysenko Date: Mon, 24 Jul 2023 21:11:04 +0300 Subject: [PATCH] docs updates (#18) --- docs/authentication.rst | 37 +++++----- docs/definitions.rst | 14 ++-- docs/deploy/index.rst | 136 +++++++++++++++++++------------------ docs/development/index.rst | 37 +++++++++- 4 files changed, 133 insertions(+), 91 deletions(-) diff --git a/docs/authentication.rst b/docs/authentication.rst index 4a686453..5872d0d2 100644 --- a/docs/authentication.rst +++ b/docs/authentication.rst @@ -33,13 +33,13 @@ Authentication headers Each ExApp request to secured API with AppEcosystemAuth must contain the following headers (order is important): -1. `AE-VERSION` - minimal version of the AppEcosystemV2 -2. `EX-APP-ID` - id of the ExApp -3. `EX-APP-VERSION` - version of the ExApp -4. `NC-USER-ID` - the user under which the request is made, can be empty in case of system apps (more details in [scopes](#AppEcosystemV2-scopes) section) -5. `AE-DATA-HASH` - hash of the request body (see details in `ae_signature`_ section) -6. `AE-SIGN-TIME` - unix timestamp of the request -7. `AE-SIGNATURE` - signature of the request (see details `ae_signature`_ section) +1. ``AE-VERSION`` - minimal version of the AppEcosystemV2 +2. ``EX-APP-ID``- id of the ExApp +3. ``EX-APP-VERSION`` - version of the ExApp +4. ``NC-USER-ID`` - the user under which the request is made, can be empty in case of system apps (more details in [scopes](#AppEcosystemV2-scopes) section) +5. ``AE-DATA-HASH`` - hash of the request body (see details in `ae_signature`_ section) +6. ``AE-SIGN-TIME`` - unix timestamp of the request +7. ``AE-SIGNATURE`` - signature of the request (see details `ae_signature`_ section) AE_SIGNATURE @@ -51,14 +51,14 @@ The signature is calculated from the following data: * method * uri (with urlencoded query parameters) -* headers (`AE-VERSION`, `EX-APP-ID`, `EX-APP-VERSION`, `NC-USER-ID`, `AE-DATA-HASH`, `AE-SIGN-TIME`) +* headers (``AE-VERSION``, ``EX-APP-ID``, ``EX-APP-VERSION``, ``NC-USER-ID``, ``AE-DATA-HASH``, ``AE-SIGN-TIME``) * xxh64 hash from request body (post data, json, files, etc.) AE_DATA_HASH ************ -`AE-DATA-HASH` header must contain a xxh64 hash of the request body. -It's calculated even if the request body is empty (e.g. empty hash: `ef46db3751d8e999`). +``AE-DATA-HASH`` header must contain a xxh64 hash of the request body. +It's calculated even if the request body is empty (e.g. empty hash: ``ef46db3751d8e999``). ExApp scopes @@ -67,15 +67,16 @@ ExApp scopes AppEcosystemV2 will support extensible scopes (with interfaces to register own ones). Currently, the following scopes are available: -* `BASIC` -* `SYSTEM` -* `USER_INFO` -* `USER_STATUS` -* `NOTIFICATIONS` -* `WEATHER_STATUS` -* `DAV` +* ``BASIC`` +* ``SYSTEM`` +* ``USER_INFO`` +* ``USER_STATUS`` +* ``NOTIFICATIONS`` +* ``WEATHER_STATUS`` +* ``FILES_SHARING`` +* ``DAV`` -There is a CLI command to list registered scopes: `occ app_ecosystem_v2:scopes:list`. +There is a CLI command to list registered scopes: ``occ app_ecosystem_v2:scopes:list``. Authentication flow in details ****************************** diff --git a/docs/definitions.rst b/docs/definitions.rst index f90382dd..f89a4fc5 100644 --- a/docs/definitions.rst +++ b/docs/definitions.rst @@ -2,9 +2,13 @@ Definitions =========== -AppEcosystemV2 brings out the following terms: +AppEcosystemV2 brings out the following terms frequently used in the code: -* ExApp (External App) - the app on another (from PHP) programming language, which can be hosted separately or inside container -* DaemonConfig - configuration of orchestration daemon (e.g. Docker) where ExApps are deployed -* ExAppConfig - similar to Nextcloud `app_config`, but for ExApps configuration -* AppEcosystemAuth - AppEcosystemV2 authentication +* ``ExApp`` (External App) - the app on another (from PHP) programming language, which uses AppEcosystemV2 API +* ``DaemonConfig`` - configuration of orchestration daemon (e.g. Docker) where ExApps are deployed +* ``DeployConfig`` - additional DaemonConfig options for orchestrator (e.g. network) and ExApps (nextcloud_url, host, etc.) +* ``ExAppConfig`` - similar to Nextcloud `app_config`, but for ExApps configuration +* ``ExAppPreferences`` - similar to Nextcloud `app_preferences`, user-specific settings for ExApps +* ``AppEcosystemAuth`` - AppEcosystemV2 authentication +* ``ExAppScope`` - granted to ExApp scope group of access to API routes +* ``ExAppApiScope`` - pre-defined scope group of access to list of API routes diff --git a/docs/deploy/index.rst b/docs/deploy/index.rst index ea1f5583..1d189ce1 100644 --- a/docs/deploy/index.rst +++ b/docs/deploy/index.rst @@ -7,20 +7,23 @@ Overview AppEcosystemV2 ExApps deployment process in short consists of 3 steps: -1. `Daemon config registration`_ +1. `DaemonConfig registration`_ 2. `ExApp deployment`_ 3. `ExApp registration`_ -Daemon config registration --------------------------- +DaemonConfig registration +------------------------- -The first step is to register Daemon config, where your ExApps will be deployed. +The first step is to register DaemonConfig, where your ExApps will be deployed. +Before that you will need to configure your Docker socket to be accessible by Nextcloud instance and webserver user. +In case of remote Docker Engine API, you will need to expose it so it is accessible by Nextcloud instance and import certificates. .. note:: - For now only Docker daemon (`accepts-deploy-id: docker-install`) is supported. + For now only Docker daemon ``accepts-deploy-id: docker-install`` is supported. + For development and manually deployed app in docker there is ``accepts-deploy-id: manual-install``. -This can be done by `occ` CLI command **app_ecosystem_v2:daemon:register**: +This can be done by ``occ`` CLI command **app_ecosystem_v2:daemon:register**: .. code-block:: bash @@ -29,27 +32,27 @@ This can be done by `occ` CLI command **app_ecosystem_v2:daemon:register**: Arguments ********* - * `name` - `[required]` unique name of the daemon (e.g. `docker_local_sock`) - * `display-name` - `[required]` name of the daemon (e.g. `My Local Docker`, will be displayed in the UI) - * `accepts-deploy-id` - `[required]` type of deployment (for now only `docker-install` is supported) - * `protocol` - `[required]` protocol used to connect to the daemon (`unix-socket`, `network`) - * `host` - `[required]` host of the daemon (e.g. `/var/run/docker.sock` for `unix-socket` protocol or `host:port` for `http(s)` protocol) - * `nextcloud_url` - `[required]` Nextcloud URL, Daemon config required option (e.g. `https://nextcloud.local`) + * ``name`` - unique name of the daemon (e.g. ``docker_local_sock``) + * ``display-name`` - name of the daemon (e.g. ``My Local Docker``, will be displayed in the UI) + * ``accepts-deploy-id`` - type of deployment (``docker-install`` or ``manual-install``) + * ``protocol`` - protocol used to connect to the daemon (``unix-socket``, ``http`` or ``https``) + * ``host`` - host of the daemon (e.g. ``/var/run/docker.sock`` for ``unix-socket`` protocol or ``host:port`` for ``http(s)`` protocol) + * ``nextcloud_url`` - Nextcloud URL, Daemon config required option (e.g. ``https://nextcloud.local``) Options ******* - * `--net [network-name]` - `[required]` network name to bind docker container to (default: `host`) - * `--host HOST` - `[required]` host to expose daemon to (defaults to ExApp appid) - * `--ssl_key SSL_KEY` - `[optional]` path to SSL key file (local absolute path) - * `--ssl_password SSL_PASSWORD` - `[optional]` SSL key password - * `--ssl_cert SSL_CERT` - `[optional]` path to SSL cert file (local absolute path) - * `--ssl_cert_password SSL_CERT_PASSWORD` - `[optional]` SSL cert password + * ``--net [network-name]`` - ``[required]`` network name to bind docker container to (default: ``host``) + * ``--host HOST`` - ``[required]`` host to expose daemon to (defaults to ExApp appid) + * ``--ssl_key SSL_KEY`` - ``[optional]`` path to SSL key file (local absolute path) + * ``--ssl_password SSL_PASSWORD`` - ``[optional]`` SSL key password + * ``--ssl_cert SSL_CERT`` - ``[optional]`` path to SSL cert file (local absolute path) + * ``--ssl_cert_password SSL_CERT_PASSWORD`` - ``[optional]`` SSL cert password -Deploy config -************* +DeployConfig +************ -Deploy config is a set of additional options in Daemon config, which are used in deployment algorithms to configure +DeployConfig is a set of additional options in Daemon config, which are used in deployment algorithms to configure ExApp container. .. code-block:: json @@ -65,24 +68,24 @@ ExApp container. } -Deploy config options -""""""""""""""""""""" +DeployConfig options +"""""""""""""""""""" - * `net` - `[required]` network name to bind docker container to (default: `host`) - * `host` - `[optional]` in case Docker is on remote host, this should be a hostname of remote machine - * `nextcloud_url` - `[required]` Nextcloud URL (e.g. `https://nextcloud.local`) - * `ssl_key` - `[optional]` path to SSL key file (local absolute path) - * `ssl_key_password` - `[optional]` SSL key password - * `ssl_cert` - `[optional]` path to SSL cert file (local absolute path) - * `ssl_cert_password` - `[optional]` SSL cert password + * ``net`` **[required]** - network name to bind docker container to (default: ``host``) + * ``host`` *[optional]* - in case Docker is on remote host, this should be a hostname of remote machine + * ``nextcloud_url`` **[required]** - Nextcloud URL (e.g. ``https://nextcloud.local``) + * ``ssl_key`` *[optional]* - path to SSL key file (local absolute path) + * ``ssl_key_password`` *[optional]* - SSL key password + * ``ssl_cert`` *[optional]* - path to SSL cert file (local absolute path) + * ``ssl_cert_password`` *[optional]* - SSL cert password .. note:: - Common configurations are tested by CI in our repository, see `workflow on github `_ + Common configurations are tested by CI in our repository, see `workflows on github `_. Example ******* -Example of `occ` **app_ecosystem_v2:daemon:register** command: +Example of ``occ`` **app_ecosystem_v2:daemon:register** command: .. code-block:: bash @@ -93,30 +96,30 @@ ExApp deployment ---------------- Second step is to deploy ExApp on registered daemon. -This can be done by `occ` CLI command **app_ecosystem_v2:app:deploy**: +This can be done by ``occ`` CLI command **app_ecosystem_v2:app:deploy**: .. code-block:: bash app_ecosystem_v2:app:deploy [--info-xml INFO-XML] [-e|--env ENV] [--] +.. note:: + For development this step is skipped, as ExApp is deployed and started manually by developer. + .. warning:: After successful deployment (pull, create and start container), there is a heartbeat check with 1 hour timeout (will be configurable). If command seems to be stuck, check if ExApp is running and accessible by Nextcloud instance. -.. note:: - For development this step is skipped, as ExApp is deployed and started manually by developer. - Arguments ********* - * `appid` - `[required]` unique name of the ExApp (e.g. `app_python_skeleton`, must be the same as in `info.xml`) - * `daemon-config-name` - `[required]` unique name of the daemon (e.g. `docker_local_sock`) + * ``appid`` - unique name of the ExApp (e.g. ``app_python_skeleton``, must be the same as in ``info.xml``) + * ``daemon-config-name`` - unique name of the daemon (e.g. ``docker_local_sock``) Options ******* - * `--info-xml INFO-XML` - `[required]` path to info.xml file (url or local absolute path) - * `-e|--env ENV` - `[optional]` additional environment variables (e.g. `-e "MY_VAR=123" -e "MY_VAR2=456"`) + * ``--info-xml INFO-XML`` **[required]** - path to info.xml file (url or local absolute path) + * ``-e|--env ENV`` *[optional]* - additional environment variables (e.g. ``-e "MY_VAR=123" -e "MY_VAR2=456"``) Deploy result JSON output ************************* @@ -143,9 +146,9 @@ Manual install for development ****************************** For development purposes, you can install ExApp manually. -There is a `manual-install` Deploy config type, which can be used in case of development. -For ExApp registration with it you need to provide JSON file with structure described before -using **app_ecosystem_v2:app:register** `--json-info` option. +There is a ``manual-install`` DeployConfig type, which can be used in case of development. +For ExApp registration with it you need to provide JSON output with structure described before +using **app_ecosystem_v2:app:register** ``--json-info`` option. Deploy env variables ******************** @@ -153,38 +156,38 @@ Deploy env variables Deploy env variables are used to configure ExApp container. The following env variables are required and built automatically: - * `AE_VERSION` - AppEcosystemV2 version - * `APP_SECRET` - generated shared secret used for AppEcosystemV2 authentication - * `APP_ID` - ExApp appid - * `APP_DISPLAY_NAME` - ExApp display name - * `APP_VERSION` - ExApp version - * `APP_PROTOCOL` - protocol ExApp is listening on (http|https) - * `APP_HOST` - host ExApp is listening on - * `APP_PORT` - port ExApp is listening on (randomly selected by AppEcosystemV2) - * `IS_SYSTEM_APP` - ExApp system app flag (true|false) - * `NEXTCLOUD_URL` - Nextcloud URL to connect to + * ``AE_VERSION`` - AppEcosystemV2 version + * ``APP_SECRET`` - generated shared secret used for AppEcosystemV2 authentication + * ``APP_ID`` - ExApp appid + * ``APP_DISPLAY_NAME`` - ExApp display name + * ``APP_VERSION`` - ExApp version + * ``APP_PROTOCOL`` - protocol ExApp is listening on (http|https) + * ``APP_HOST`` - host ExApp is listening on + * ``APP_PORT`` - port ExApp is listening on (randomly selected by AppEcosystemV2) + * ``IS_SYSTEM_APP`` - ExApp system app flag (true|false) + * ``NEXTCLOUD_URL`` - Nextcloud URL to connect to .. note:: - Additional envs can be passed using multiple `--env ENV_NAME=ENV_VAL` options + Additional envs can be passed using multiple ``--env ENV_NAME=ENV_VAL`` options Docker daemon remote ******************** If you want to connect to remote docker daemon with TLS enabled, you need to provide SSL key and cert by provided options. -Important: before deploy you need to import ca.pem file using occ command: +Important: before deploy you need to import ca.pem file using `occ security `_ command: -``` -php occ security:certificates:import /path/to/ca.pem -``` +``php occ security:certificates:import /path/to/ca.pem`` -The daemon must be configured with `protocol=http|https`, `host=https://dockerapihost`, `port=8443`. +The daemon must be configured with ``protocol=http|https``, ``host=https://dockerapihost``, ``port=8443``. +DaemonConfig deploy options ``ssl_key`` and ``ssl_cert`` must be provided with local absolute paths to SSL key and cert files. +In case of password protected key or cert, you can provide ``ssl_key_password`` and ``ssl_cert_password`` options. More info about how to configure daemon will be added soon. ExApp registration ------------------ Final step is to register ExApp in Nextcloud. -This can be done by `occ` CLI command **app_ecosystem_v2:app:register**: +This can be done by ``occ`` CLI command **app_ecosystem_v2:app:register**: .. code-block:: bash @@ -193,15 +196,18 @@ This can be done by `occ` CLI command **app_ecosystem_v2:app:register**: Arguments ********* - * `appid` - `[required]` unique name of the ExApp (e.g. `app_python_skeleton`, must be the same as in deployed container) - * `daemon-config-name` - `[required]` unique name of the daemon (e.g. `docker_local_sock`) + * ``appid`` - unique name of the ExApp (e.g. ``app_python_skeleton``, must be the same as in deployed container) + * ``daemon-config-name`` - unique name of the daemon (e.g. ``docker_local_sock``) Options ******* - * `-e|--enabled` - `[optional]` enable ExApp after registration - * `--force-scopes` - `[optional]` force scopes approval - * `--json-info JSON-INFO` - `[required]` path to JSON file with deploy result (url or local absolute path) + * ``-e|--enabled`` *[optional]* - enable ExApp after registration + * ``--force-scopes`` *[optional]* - force scopes approval + * ``--json-info JSON-INFO`` **[required]** - path to JSON file with deploy result (url or local absolute path) + +With provided ``appid`` and ``daemon-config-name``, Nextcloud will retrieve ExApp info from deployed container and register it. +In case of ``manual-install`` DeployConfig type, ExApp info must be provided by ``--json-info`` option `as described before <#deploy-result-json-output>`_. ExApp info.xml schema --------------------- diff --git a/docs/development/index.rst b/docs/development/index.rst index d56881c2..9aebdc9d 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -2,10 +2,41 @@ Development =========== -This section will contain all the information required to develop the project. +This section will contain necessary information regarding development process of the project. +Pre-condition +^^^^^^^^^^^^^ -Requirements ------------- +To make development commands work, we assume that your development environment is setup using `nextcloud-docker-dev `_. +Make commands +^^^^^^^^^^^^^ +There are several make commands available to ease frequent development actions. +You can see all of them by running ``make help``. + + +Docker remote API +***************** + +The Docker Engine remote API can be easily configured via ``make dock2port`` and ``make dock-certs`` commands. +The first one will create a docker container to provide remote Docker Engine API. +The second one will configure generated certificates for created container with Docker remote API in Nextcloud. + +After that register DaemonConfigs in Nextcloud using ``make dock-port`` command. + +Docker by socket +**************** + +If you want to use Docker by socket, use ``make dock2sock`` command. +It will register DaemonConfigs in Nextcloud for default socket connection (``/var/run/docker.sock``). +Make sure that this socket has enough permissions for Nextcloud and webserver user to access it +and actually forwarded to the container: + +.. code-block:: + + ... + volumes: + ... + - /var/run/docker.sock:/var/run/docker.sock + ...