adjusting deploy daemon docs for AppAPI 2.0 (#218)

Closes: #98 --------- Signed-off-by: Alexander Piskun <[email protected]> Signed-off-by: Andrey Borysenko <[email protected]> Co-authored-by: Andrey Borysenko <[email protected]>
nextcloud · Jan 26, 2024 · 500453b · 500453b
1 parent 826aa74
commit 500453b
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 88 deletions.
diff --git a/docs/CreationOfDeployDaemon.rst b/docs/CreationOfDeployDaemon.rst
@@ -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
 ^^^^^^^
@@ -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

diff --git a/docs/DeployConfigurations.rst b/docs/DeployConfigurations.rst
@@ -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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -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::
 
@@ -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
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -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::
 
@@ -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::
@@ -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)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -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.
diff --git a/lib/DeployActions/AIODockerActions.php b/lib/DeployActions/AIODockerActions.php
@@ -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',