Skip to content

Commit

Permalink
docs updates (#18)
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrey18106
andrey18106 authored Jul 24, 2023
1 parent 526a755 commit fcc0475
Show file tree
Hide file tree
Showing 4 changed files with 133 additions and 91 deletions.
37 changes: 19 additions & 18 deletions docs/authentication.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
******************************
Expand Down
14 changes: 9 additions & 5 deletions docs/definitions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
136 changes: 71 additions & 65 deletions docs/deploy/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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 <https://github.com/cloud-py-api/app_ecosystem_v2/blob/main/.github/workflows/tests-deploy.yml>`_
Common configurations are tested by CI in our repository, see `workflows on github <https://github.com/cloud-py-api/app_ecosystem_v2/blob/main/.github/workflows/tests-deploy.yml>`_.

Example
*******

Example of `occ` **app_ecosystem_v2:daemon:register** command:
Example of ``occ`` **app_ecosystem_v2:daemon:register** command:

.. code-block:: bash
Expand All @@ -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 <appid> <daemon-config-name> [--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
*************************
Expand All @@ -143,48 +146,48 @@ 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
********************

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 <https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html#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
Expand All @@ -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
---------------------
Expand Down
37 changes: 34 additions & 3 deletions docs/development/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/juliushaertl/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
...

0 comments on commit fcc0475

Please sign in to comment.