Skip to content

Commit

Permalink
adjusting deploy daemon docs for AppAPI 2.0 (#218)
Browse files Browse the repository at this point in the history 
Closes: #98

---------

Signed-off-by: Alexander Piskun <bigcat88@icloud.com>
Signed-off-by: Andrey Borysenko <andrey18106x@gmail.com>
Co-authored-by: Andrey Borysenko <andrey18106x@gmail.com>
  • Loading branch information
@bigcat88 @andrey18106
bigcat88 and andrey18106 authored Jan 26, 2024
1 parent 826aa74 commit 500453b
Show file tree
Hide file tree
Showing 3 changed files with 58 additions and 88 deletions.
7 changes: 5 additions & 2 deletions docs/CreationOfDeployDaemon.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ The recommended daemon configuration is using `AppAPI Docker Socket Proxy <https
.. image:: ../screenshots/app_api_3.png


You can choose one of basic configuration templates and adjust to your needs.
You can choose one of the basic configuration templates and adjust to your needs.

.. note:: We highly recommend to use UI to create Deploy Daemons.

OCC CLI
^^^^^^^
Expand All @@ -38,7 +40,8 @@ Arguments
* ``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`` - **path to docker-socket** or the Docker Socket Proxy: ``address:port``
* ``protocol`` - protocol used to communicate with the Daemon/ExApps (``http`` or ``https``)
* ``nextcloud_url`` - Nextcloud URL, Daemon config required option (e.g. ``https://nextcloud.local``)

Options
Expand Down
137 changes: 52 additions & 85 deletions docs/DeployConfigurations.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,23 +13,19 @@ Orchestrates the deployment of applications as Docker containers.

.. warning::

The administrator is responsible for the security actions taken to configure the Docker daemon connected to Nextcloud.
We recommend that you use the `AppAPI Docker Socket Proxy <https://github.com/cloud-py-api/docker-socket-proxy>`_ as the Deploy Daemon,
it has stringent security rules and is easy to configure, `like in AIO <#nextcloud-in-docker-aio-all-in-one>`_.
The administrator is responsible for the security actions taken to configure the Docker daemon connected to the Nextcloud instance.

There are several Docker Daemon Deploy configurations (example schemes):
These schemes are only examples of possible configurations.

* Nextcloud and Docker on the **same host** (via socket or port)
* Nextcloud on the host and Docker on a **remote** host (via port)
* Nextcloud and **ExApps** in the **same Docker** (via socket or port)
* Nextcloud in AIO Docker and **ExApps** in the **same Docker** (via socket proxy)
We recommend that you use the `AppAPI Docker Socket Proxy <https://github.com/cloud-py-api/docker-socket-proxy>`_ or `AIO Docker Socket Proxy <#nextcloud-in-docker-aio-all-in-one>`_ container.

In the case of remote access to the Daemon, make certain that it's configured with **ssl_key**, **ssl_cert**, and **ca.cert**, and that the latter is imported into Nextcloud.
There are several Docker Daemon Deploy configurations (example schemes):

.. note::
* Nextcloud and Docker on the **same host** (via socket or DockerSocketProxy)
* Nextcloud on the host and Docker on a **remote** host (via DockerSocketProxy with HTTPS)
* Nextcloud and **ExApps** in the **same Docker** (via DockerSocketProxy)
* Nextcloud in AIO Docker and **ExApps** in the **same Docker** (via AIO DockerSocketProxy)

These schemes are only examples of possible configurations.
We recommend that you use the Docker Socket Proxy container as the Deploy Daemon.

NC & Docker on the Same-Host
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -64,7 +60,15 @@ The simplest configuration is when Nextcloud is installed on the host and Docker
class ExApp2 python
class ExApp3 python

Suggested way to communicate with Docker: via ``docker-socket-proxy``.
Suggested config values(template *Custom default*):
1. Daemon host: ``/var/run/docker.sock``
2. HTTPS checkbox: *not supported using docker socket*
3. Network: ``host``
4. HaProxy password: *not supported using docker socket*

---

Suggested way to communicate with Docker via `Docker Socket Proxy container <https://github.com/cloud-py-api/docker-socket-proxy>`_.

.. mermaid::

Expand Down Expand Up @@ -93,8 +97,20 @@ Suggested way to communicate with Docker: via ``docker-socket-proxy``.
class ExApp2 python
class ExApp3 python

Suggested config values(template *Docker Socket Proxy*):
1. Daemon host: ``localhost:2375``
Choose **A** or **B** option:
A. Docker Socket Proxy should be deployed with ``network=host`` and ``BIND_ADDRESS=127.0.0.1``
B. Docker Socket Proxy should be deployed with ``network=bridge`` and it's port should be published to host's 127.0.0.1(e.g. **-p 127.0.0.1:2375:2375**)
2. HTTPS checkbox: **disabled**
3. Network: ``host``
4. HaProxy password: **can be empty**

.. warning::

Be careful with option ``A``, by default **Docker Socket Proxy** binds to ``*`` if ``BIND_ADDRESS`` is not specified during container creation.
Check opened ports after finishing configuration(*or set HaProxy password*).

`Docker Socket Proxy container <https://github.com/nextcloud/all-in-one/tree/main/Containers/docker-socket-proxy>`_ can be used for that.

Docker on a remote host
^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -103,40 +119,7 @@ Distributed configuration occurs when Nextcloud is installed on one host and Doc

Benefit: no performance impact on Nextcloud host.

.. mermaid::

stateDiagram-v2
classDef docker fill: #1f97ee, color: transparent, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/cloud-py-api/app_api/main/docs/img/docker.png) no-repeat center center / contain
classDef nextcloud fill: #006aa3, color: transparent, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/cloud-py-api/app_api/main/docs/img/nextcloud.svg) no-repeat center center / contain
classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px

Direction LR

Host1 --> Host2 : by port

state Host1 {
Nextcloud
}

state Host2 {
Daemon --> Containers

state Containers {
ExApp1
--
ExApp2
--
ExApp3
}
}

class Nextcloud nextcloud
class Daemon docker
class ExApp1 python
class ExApp2 python
class ExApp3 python

In this case, the AppAPI (Nextcloud) uses ``port`` to interact with remote Docker, which also could be a Docker Socket Proxy exposed with TLS.
In this case, the AppAPI uses a Docker Socket Proxy deployed on remote host to access docker socket and ExApps.

.. mermaid::

Expand Down Expand Up @@ -171,38 +154,17 @@ In this case, the AppAPI (Nextcloud) uses ``port`` to interact with remote Docke
class ExApp2 python
class ExApp3 python

Suggested config values(template *Docker Socket Proxy*):
1. Daemon host: ADDRESS_OF_REMOTE_MACHINE (e.g. **server_name.com:2375**)
2. HTTPS checkbox: ``enabled``
3. Network: ``host``
4. HaProxy password: ``your chosen password``

NC & ExApps in the same Docker
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Applications are deployed in the same docker where Nextcloud resides.

.. mermaid::

stateDiagram-v2
classDef docker fill: #1f97ee, color: transparent, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/cloud-py-api/app_api/main/docs/img/docker.png) no-repeat center center / contain
classDef nextcloud fill: #006aa3, color: transparent, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/cloud-py-api/app_api/main/docs/img/nextcloud.svg) no-repeat center center / contain
classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px

Host

state Host {
Daemon --> Containers

state Containers {
[*] --> Nextcloud : /var/run/docker.sock
--
ExApp1
--
ExApp2
}
}

class Nextcloud nextcloud
class Daemon docker
class ExApp1 python
class ExApp2 python
class ExApp3 python

Suggested way to communicate with Docker: via ``docker-socket-proxy``.

.. mermaid::
Expand Down Expand Up @@ -232,6 +194,17 @@ Suggested way to communicate with Docker: via ``docker-socket-proxy``.
class ExApp2 python
class ExApp3 python

Suggested config values(template *Docker Socket Proxy*):
1. Daemon host: aa-docker-socket-proxy:2375
2. HTTPS checkbox: ``disabled``
3. Network: `user defined network <https://docs.docker.com/network/#user-defined-networks>`_
4. HaProxy password: ``optional``

.. note::
Network **should not be the default docker's bridge** as it does not support DNS resolving by container names.

This means that **Docker Socket Proxy**, **Nextcloud** and **ExApps** containers should all be in the same docker network, different from the default **bridge**.

Nextcloud in Docker AIO (all-in-one)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -291,20 +264,14 @@ It has `fixed parameters <https://github.com/cloud-py-api/app_api/blob/main/lib/
* Accepts Deploy ID: ``docker-install``
* Protocol: ``http``
* Host: ``nextcloud-aio-docker-socket-proxy:2375``
* GPUs support: If enabled during AIO setup (``NEXTCLOUD_ENABLE_DRI_DEVICE=true``)
* GPUs support: ``false``
* Network: ``nextcloud-aio``
* Nextcloud URL (passed to ExApps): ``https://$NC_DOMAIN``

.. note::
If ``NEXTCLOUD_ENABLE_DRI_DEVICE=true`` is set - separate DaemonConfig (``docker_aio_gpu``) will be created with ``gpus=true``.

Docker Socket Proxy security
****************************

AIO Docker Socket Proxy has strictly limited access to the Docker APIs described in `HAProxy configuration <https://github.com/nextcloud/all-in-one/blob/main/Containers/docker-socket-proxy/haproxy.cfg>`_.

Network configurations
----------------------

When GUI will support all command line options like: ``hostname``, ``ssl_key``... they will be described here.

If you want to run ExApp on the remote host, see :ref:`occ cli commands <occ_daemon_config_registration>` for it.

.. note:: AppAPI does not currently support automatic configuration for applications to use **https**, but we have plans for this in the future.
2 changes: 1 addition & 1 deletion lib/DeployActions/AIODockerActions.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ private function registerAIODaemonConfigWithGPU(): ?DaemonConfig {
];

$daemonConfigParams = [
'name' => self::AIO_DAEMON_CONFIG_NAME,
'name' => self::AIO_DAEMON_CONFIG_NAME_GPU,
'display_name' => 'AIO Docker Socket Proxy with GPU',
'accepts_deploy_id' => 'docker-install',
'protocol' => 'http',
Expand Down

0 comments on commit 500453b

Please sign in to comment.