feat(Admin/AppAPI): add HaRP documentation (#13070)

Signed-off-by: Anupam Kumar <kyteinsky@gmail.com>

admin_manual/exapps_management/AppAPIAndExternalApps.rst

@@ -20,12 +20,44 @@ If AppAPI is not installed, you can still install it by simply navigating to the
 Setup deploy daemon
 -------------------
 
-A Deploy Daemon is a way for Nextcloud to install, communicate with, and control ExApps.
+A Deploy Daemon is the way for Nextcloud to install, communicate with, and control ExApps.
 
 .. note::
-	If you are using Nextcloud AIO with the "Docker Socket Proxy" container enabled, a Deploy Daemon will be automatically created and configured to work out-of-the-box.
+	If you are using Nextcloud AIO with the "HaRP" or "Docker Socket Proxy" container enabled, a Deploy Daemon will be automatically created and configured to work out-of-the-box.
 	Otherwise, follow the steps below to set up a Deploy Daemon from the AppAPI admin settings.
 
+.. _ai-app_api_harp:
+
+HaRP
+~~~~
+
+| This is the newer and the **recommended** way to install ExApps.
+| It requires changes in the proxy of your Nextcloud instance. If you don't have access to the proxy, you can use the usual method :ref:`described below <ai-app_api_dsp>`.
+
+1. Setup a Docker container called `HaRP <https://github.com/nextcloud/HaRP?tab=readme-ov-file#how-to-install-it>`_ that proxies access to Docker and to the ExApps for your Nextcloud instance. Be mindful of changing the values of ``HP_SHARED_KEY`` and ``NC_INSTANCE_URL``.
+2. Go to AppAPI admin settings.
+3. Click on the "Register Daemon" button.
+4. | A filled form should appear. This default configuration ``HaRP Proxy (Host)`` should work for most setups. For Nextcloud AIO, use ``HaRP All-in-One``.
+   | If you are using Nextcloud in a custom docker network and would want the HaRP container to be limited to it, use the ``HaRP Proxy (Docker)`` option to have the fields pre-filled with the common options or change them manually.
+   | Here, you should ensure the HaRP container itself is launched with the same network as your Nextcloud instance optionally with no ports exposed to the host in step 1, and the same docker network is mentioned in the ``Network`` field in the deploy config.
+5. Ensure the same shared key is used in the HaRP container and in the AppAPI settings.
+6. Click "Check connection" to verify that the configuration is correct.
+7. Click "Register" to save the Deploy Daemon configuration.
+8. Set up a location redirect in your Nextcloud's main proxy configuration to redirect requests to the HaRP container. Some examples for popular reverse proxies can be found in `Configuring Your Reverse Proxy <https://github.com/nextcloud/harp?tab=readme-ov-file#configuring-your-reverse-proxy>`_ in the HaRP readme.
+9. Test the whole setup with "Test deploy" in the 3-dots menu of the Deploy Daemon.
+
+This is suitable for local setups where the Nextcloud server and the ExApps are on the same machine or in the same docker network.
+The ExApps in this configuration or the ExApp server need not expose any ExApp related port (23000-23999) necessarily to the host, nor do they need to be reachable from the host. They should be able to reach the HaRP container at the FRP port and the Nextcloud instance.
+For different/remote setups, see deployment configuration examples :doc:`here <./DeployConfigurations>`.
+
+.. note::
+	The existing ExApps can be migrated to use the new HaRP proxy following `this guide <https://github.com/nextcloud/harp?tab=readme-ov-file#nextcloud-32-migrating-existing-exapps-from-dsp-to-harp>`_.
+
+.. _ai-app_api_dsp:
+
+Docker Socket Proxy
+~~~~~~~~~~~~~~~~~~~~
+
 1. Setup a Docker container called `docker-socket-proxy <https://github.com/nextcloud/docker-socket-proxy#readme>`_ that proxies access to Docker for your Nextcloud instance.
 2. Go to the AppAPI admin settings.
 3. Click on the "Register Daemon" button.
@@ -73,3 +105,58 @@ FAQ
     * Parallel processing of AI workloads for the same app with multiple GPUs is currently not supported.
 * Can I use the CPU and GPU in parallel for AI processing?
     * No, you can only process AI workloads on either the CPU or GPU for one app. For different apps, you can decide whether to run them on CPU or GPU.
+
+Docker Socket Proxy vs HaRP
+---------------------------
+
+| HaRP can be seen as Docker Socket Proxy version 2.0. It does all what Docker Socket Proxy does, but also addresses the main pain point of ExApps not being reachable by the Nextcloud server (or AppAPI).
+| `FRP <https://github.com/fatedier/frp>`_ is used to create a tunnel between the ExApp and the HaRP container so there is no need for the ExApp containers to expose any ports to the host or to be reachable from the Nextcloud server.
+| The Nextcloud server can reach the ExApp containers through the HaRP container.
+
+HaRP has an additional benefit of being able to proxy requests coming from the Web interface or an API to the ExApp container without being proxies through the Nextcloud server, saving resources, improving performance and supporting additional protocols like WebSockets.
+
+HaRP is the recommended way to run ExApps, but if you are not able to use it, Docker Socket Proxy is still supported.
+
+Frontend requests in case of Docker Socket Proxy:
+
+.. mermaid::
+
+	graph LR;
+		subgraph Browser
+			A[Frontend]
+		end
+
+		B[Proxy]
+
+		subgraph Services behind the proxy
+			C[Dcker Socket Proxy]
+			D[ExApp]
+			E[Nextcloud Server / AppAPI]
+		end
+
+		A --> B
+		B -->|Request to an ExApp| E --Converted to ExApp auth--> D
+		B -->|All other usual requests| E
+
+
+Frontend requests in case of HaRP:
+
+.. mermaid::
+
+	graph LR;
+		subgraph Browser
+			A[Frontend]
+		end
+
+		B[Proxy]
+
+		subgraph Services behind the proxy
+			C[HaRP]
+			D[ExApp]
+			E[Nextcloud Server / AppAPI]
+		end
+
+		B --All other usual requests--> E
+		A --> B
+		B --Direct request to an ExApp--> C --Converted to ExApp auth--> D
+		C --User auth validation--> E

admin_manual/exapps_management/DeployConfigurations.rst

@@ -3,8 +3,9 @@
 Deployment configurations
 =========================
 
-Currently, only one kind of application deployment is supported:
-	* **Docker Deploy Daemon**
+Currently, two kinds of application deployments are supported:
+	* :ref:`Docker Deploy Daemon (Docker Socket Proxy) <ai-app_api_ddd-dsp>`
+	* :ref:`Docker Deploy Daemon (HaRP) <ai-app_api_ddd-harp>`
 
 Docker Deploy Daemon
 --------------------
@@ -13,20 +14,187 @@ 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 the Nextcloud instance.
+	| The administrator is responsible for the security actions taken to configure the Docker daemon connected to the Nextcloud instance.
+	| These schemes are only examples of possible configurations.
 
-	These schemes are only examples of possible configurations.
-
-	We recommend that you use the `AppAPI Docker Socket Proxy <https://github.com/nextcloud/docker-socket-proxy>`_ or `AIO Docker Socket Proxy <#nextcloud-in-docker-aio-all-in-one>`_ container.
+	| For Docker Deploy Daemon (HaRP), `AppAPI HaRP <https://github.com/nextcloud/harp>`_ is required or `AIO HaRP <#nextcloud-in-aio-and-docker-on-the-same-host>`_ for Nextcloud AIO.
+	| For Docker Deploy Daemon (Docker Socket Proxy), we recommend that you use the `AppAPI Docker Socket Proxy <https://github.com/nextcloud/docker-socket-proxy>`_ or `AIO Docker Socket Proxy <#nextcloud-in-docker-aio-all-in-one>`_ container for Nextcloud AIO.
 
 There are several Docker Daemon Deploy configurations (example schemes):
 
-	* 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)
+	* Nextcloud and Docker on the **same host** (via socket, DockerSocketProxy, or HaRP)
+	* Nextcloud on the host and Docker on a **remote** host (via DockerSocketProxy with HTTPS, or HaRP)
+	* Nextcloud and **ExApps** in the **same Docker network** (via DockerSocketProxy, or HaRP)
+	* Nextcloud in AIO Docker and **ExApps** in the **same Docker network** (via AIO DockerSocketProxy or HaRP)
 
 
+.. _ai-app_api_ddd-harp:
+
+Docker Deploy Daemon (HaRP)
+---------------------------
+
+| With HaRP, the ExApps initiate the connection for tunneling to the Nextcloud instance and the HaRP container so there is no need to expose any ports or open any firewall rules.
+| See the diagrams of the respective configurations in the :ref:`Docker Deploy Daemon (Docker Socket Proxy) <ai-app_api_ddd-dsp>` section below.
+
+A little introduction to the default ports of the HaRP container is given below. More about it can be found in the `HaRP's readme <https://github.com/nextcloud/harp?tab=readme-ov-file#environment-variables>`_.
+
+* Port ``8780`` is the HTTP communication port used where Nextcloud connects to the HaRP container.
+* Port ``8781`` is the HTTPS communication port when setup.
+* Port ``8782`` is the FRP tunnel port used by ExApps to connect to the HaRP container.
+
+In any of the cases, the following connections should succeed:
+
+* Nextcloud -> HaRP container (on port 8780/8781)
+* HaRP container -> Nextcloud (through proxy or directly as the NC_INSTANCE_URL env var dictates)
+* ExApp -> HaRP container (on port 8782)
+* ExApp -> Nextcloud (through proxy or directly as the ``Nextcloud URL`` in the daemon config dictates)
+
+TODO: open the website session, cert for https
+
+.. _ai-app_api_nc-harp-baremetal:
+
+Nextcloud and Docker on the same host - with Nextcloud bare metal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The simplest configuration is when Nextcloud is installed on the host and docker is on the same host and applications are deployed to it.
+
+Create a HaRP container with either ``--network host`` option or expose the ports ``8780`` and ``8782`` to the host.
+
+.. code-block:: bash
+
+  docker run \
+    -e HP_SHARED_KEY="some_very_secure_password" \
+    -e NC_INSTANCE_URL="https://127.0.0.1:8080" \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -v `pwd`/certs:/certs \
+    --name appapi-harp -h appapi-harp \
+    --restart unless-stopped \
+    -p 8780:8780 \
+    -p 8782:8782 \
+    -d ghcr.io/nextcloud/nextcloud-appapi-harp:release
+
+Go to AppAPI admin settings and register a ``HaRP Proxy (Host)`` daemon.
+
+.. image:: ./img/harp_host.png
+
+Finally, test the whole setup with "Test deploy" in the 3-dots menu of the deploy daemon.
+
+Nextcloud and Docker on the same host - with Nextcloud in Docker
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When Nextcloud is installed in Docker, the HaRP container can be created in the same docker network as the Nextcloud instance.
+
+Create a HaRP container with ``--network <nextcloud_docker_network_name>`` option, where ``<nextcloud_docker_network_name>`` is the name of the Docker network in which Nextcloud is accessible.
+
+.. code-block:: bash
+
+  docker run \
+    -e HP_SHARED_KEY="some_very_secure_password" \
+    -e NC_INSTANCE_URL="https://nextcloud.tld" \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -v `pwd`/certs:/certs \
+    --name appapi-harp -h appapi-harp \
+    --restart unless-stopped \
+    --net <nextcloud_docker_network_name> \
+    -d ghcr.io/nextcloud/nextcloud-appapi-harp:release
+
+Go to AppAPI admin settings and register a ``HaRP Proxy (Docker)`` daemon. Take note of the ``<nextcloud_docker_network_name>`` value in the ``Docker network`` field.
+
+.. image:: ./img/harp_docker.png
+
+Finally, test the whole setup with "Test deploy" in the 3-dots menu of the deploy daemon.
+
+Docker on a remote host - with HaRP container on the local host
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This configuration is suited for deployments that want to offload the heavy lifting of the ExApps to a remote host, especially when using GPUs as compute devices. There can be multiple deploy daemons that can be used to deploy ExApps on different remote hosts for different compute capabilities.
+Here the HaRP container is deployed on the local host and the remote host tunnels the remote host's docker socket to the local host over the `FRP <https://github.com/fatedier/frp>`_ secure tunnel. The ExApps are deployed on the remote host.
+A setup with the HaRP container itself on the remote is not supported.
+
+1. Create a HaRP container in the local host following :ref:`the above examples <ai-app_api_nc-harp-baremetal>` but without the docker socket mount.
+
+  .. code-block:: bash
+
+    docker run \
+      -e HP_SHARED_KEY="some_very_secure_password" \
+      -e NC_INSTANCE_URL="https://127.0.0.1:8080" \
+      -v `pwd`/certs:/certs \
+      --name appapi-harp -h appapi-harp \
+      --restart unless-stopped \
+      -p 8780:8780 \
+      -p 8782:8782 \
+      -d ghcr.io/nextcloud/nextcloud-appapi-harp:release
+
+2. Create a matching deploy daemon with ``Docker socket proxy port`` set to ``24001``.
+
+  .. image:: ./img/harp_remote_24001.png
+
+3. The FRP generated client certificates should be present in the ``certs`` folder locally. Copy the files ``client.crt``, ``client.key`` and ``ca.crt`` inside the ``certs`` folder to the remote host.
+4. Create a folder structure on the remote host: ``mkdir -p certs/frp`` and copy the files ``client.crt``, ``client.key`` and ``ca.crt`` to the ``certs/frp`` folder.
+5. Create a new file ``frpc.toml`` with the following contents. 
+
+	.. code-block:: toml
+
+		# frpc.toml
+		serverAddr = "your.harp.server.address"          # Replace with your HP_FRP_ADDRESS host
+		serverPort = 8782                                # Default port for FRP or the port your reverse proxy listens on
+		loginFailExit = false                            # If the FRP (HaRP) server is unavailable, continue trying to log in.
+
+		transport.tls.certFile = "certs/frp/client.crt"
+		transport.tls.keyFile = "certs/frp/client.key"
+		transport.tls.trustedCaFile = "certs/frp/ca.crt"
+		transport.tls.serverName = "harp.nc"             # DO NOT CHANGE THIS VALUE
+
+		metadatas.token = "some_very_secure_password"    # HP_SHARED_KEY in quotes
+
+		[[proxies]]
+		remotePort = 24001                               # Unique remotePort for each Docker Engine (range: 24001-24099)
+		name = "deploy-daemon-1"                         # Unique name for each Docker Engine
+		type = "tcp"
+		[proxies.plugin]
+		type = "unix_domain_socket"
+		unixPath = "/var/run/docker.sock"
+
+   | Make sure to replace the ``your.harp.server.address`` with the actual address of the local host where the HaRP container is running.
+   | You might want to open the port ``8782`` on the local host firewall to allow the remote host to connect to it,
+   | or use a reverse proxy to forward the requests to the HaRP container. An example with nginx is given below. Feel free to adjust the port you want to listen on. The FRP client will connect to this port exposed port.
+   | With the reverse proxy config below, the whole setup would only need the main Nextcloud proxy to be exposed and reachable from the outside world, simplifying the network setup.
+
+	.. code-block:: nginx
+
+		stream {
+		    server {
+		        listen 8782;  # Replace with the port you want to listen on
+		        proxy_pass 127.0.0.1:8782;
+		        proxy_protocol off;
+		        proxy_connect_timeout 10s;
+		        proxy_timeout 300s;
+		    }
+		}
+
+6. Download a release of the FRP client from `the official releases <https://github.com/fatedier/frp/releases/latest>`_ or `our snapshot from here <https://github.com/nextcloud/HaRP/tree/main/exapps_dev>`_.
+7. Extract and copy the ``frpc`` binary to an appropriate location on the remote host, e.g. ``/usr/local/bin``.
+8. Make it executable: ``chmod +x /usr/local/bin/frpc``.
+9. Start the FRP client with the command: ``frpc -c /path/to/frpc.toml``.
+10. Finally, test the whole setup with "Test deploy" in the 3-dots menu of the deploy daemon.
+
+Nextcloud in AIO and Docker on the same host
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Nextcloud AIO (All-in-One) comes with a built-in HaRP container that can be used to deploy ExApps on the same host.
+Enabling the "HaRP" container should automatically create a Deploy Daemon and configure it to work out-of-the-box.
+
+Just go to AppAPI admin settings and register a ``HaRP All-in-One`` daemon.
+
+.. image:: ./img/harp_aio.png
+
+Finally, test the whole setup with "Test deploy" in the 3-dots menu of the deploy daemon.
+
+.. _ai-app_api_ddd-dsp:
+
+Docker Deploy Daemon (Docker Socket Proxy)
+------------------------------------------
+
 NC & Docker on the Same-Host
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -256,8 +424,8 @@ AppAPI will automatically create the default DaemonConfig for AIO Docker Socket
 	Default DaemonConfig will be created only if the default DaemonConfig is not already registered.
 
 
-Default AIO Deploy Daemon
-*************************
+Default AIO Deploy Daemon (Docker Socket Proxy)
+***********************************************
 
 Nextcloud AIO has a specifically created Docker Socket Proxy container to be used as the Deploy Daemon in AppAPI.
 It has `fixed parameters <https://github.com/nextcloud/app_api/blob/main/lib/DeployActions/AIODockerActions.php#L52-L74)>`_:
@@ -280,6 +448,10 @@ AIO Docker Socket Proxy has strictly limited access to the Docker APIs described
 NC to ExApp Communication
 -------------------------
 
+Communications between Nextcloud and ExApps are done via the AppAPI.
+With Docker Socket Proxy, the requests are sent to the ExApp container directly.
+For HaRP, the communication goes through the main Nextcloud proxy and the HaRP container.
+
 Each type of DeployDaemon necessarily implements the ``resolveExAppUrl`` function.
 
 It has the prototype:
@@ -300,6 +472,8 @@ where:
 
 .. note::
 
+	Applies only to Docker Socket Proxy.
+
 	The optional additional parameter *OVERRIDE_APP_HOST* can be used to
 	override the host that will be used for ExApp binding.
 
@@ -316,6 +490,14 @@ The simplest implementation is in the **Manual-Install** deploy type:
 	public function resolveExAppUrl(
 		string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth
 	): string {
+		if (boolval($deployConfig['harp'] ?? false)) {
+			$url = rtrim($deployConfig['nextcloud_url'], '/');
+			if (str_ends_with($url, '/index.php')) {
+				$url = substr($url, 0, -10);
+			}
+			return sprintf('%s/exapps/%s', $url, $appId);
+		}
+
 		$auth = [];
 		if (isset($deployConfig['additional_options']['OVERRIDE_APP_HOST']) &&
 			$deployConfig['additional_options']['OVERRIDE_APP_HOST'] !== ''
@@ -328,7 +510,8 @@ The simplest implementation is in the **Manual-Install** deploy type:
 		return sprintf('%s://%s:%s', $protocol, $host, $port);
 	}
 
-Here we see that AppAPI sends requests to the **host**:**port** specified during daemon creation.
+| Here we see that AppAPI sends requests to the **host**:**port** specified during daemon creation for manual-install without HaRP.
+| But it exclusively uses the ``http(s)://nextcloud.example.tld/exapps/`` route for manual deployments using the HaRP proxy. ``http(s)://nextcloud.example.tld`` is the Nextcloud URL specified in the daemon config. Take care to configure the ``/exapps/`` route in your reverse proxy accordingly if your Nextcloud instance is on a subpath ``https://nextcloud.example.tld/nextcloud``. See `Configuring Your Reverse Proxy <https://github.com/nextcloud/harp?tab=readme-ov-file#configuring-your-reverse-proxy>`_ in the HaRP readme for examples.
 
 Now, let's take a look at the Docker Daemon implementation of ``resolveExAppUrl``:
 
@@ -337,6 +520,14 @@ Now, let's take a look at the Docker Daemon implementation of ``resolveExAppUrl`
 	public function resolveExAppUrl(
 		string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth
 	): string {
+		if (boolval($deployConfig['harp'] ?? false)) {
+			$url = rtrim($deployConfig['nextcloud_url'], '/');
+			if (str_ends_with($url, '/index.php')) {
+				$url = substr($url, 0, -10);
+			}
+			return sprintf('%s/exapps/%s', $url, $appId);
+		}
+
 		$auth = [];
 		if (isset($deployConfig['additional_options']['OVERRIDE_APP_HOST']) &&
 			$deployConfig['additional_options']['OVERRIDE_APP_HOST'] !== ''
@@ -356,13 +547,17 @@ Now, let's take a look at the Docker Daemon implementation of ``resolveExAppUrl`
 		} else {
 			$exAppHost = $appId;
 		}
-		if (isset($deployConfig['haproxy_password']) && $deployConfig['haproxy_password'] !== '') {
-			$auth = [self::APP_API_HAPROXY_USER, $deployConfig['haproxy_password']];
+		if ($protocol == 'https' && isset($deployConfig['haproxy_password']) && $deployConfig['haproxy_password'] !== '') {
+			// we only set haproxy auth for remote installations, when all requests come through HaProxy.
+			$haproxyPass = $this->crypto->decrypt($deployConfig['haproxy_password']);
+			$auth = [self::APP_API_HAPROXY_USER, $haproxyPass];
 		}
 		return sprintf('%s://%s:%s', $protocol, $exAppHost, $port);
 	}
 
-Here we have much more complex algorithm of detecting to where requests should be send.
+The route for HaRP setups remain the same here as in the previous example. All the requests are sent to the Nextcloud URL with the ``/exapps/`` route.
+
+For Docker Socket Proxy, however, we have much more complex algorithm of detecting to where requests should be send.
 
 First of all, if the protocol is set to ``https``, AppAPI always sends requests to the daemon host,
 and in this case, it is a HaProxy that will forward requests to ExApps that will be listening on ``localhost``.

admin_manual/exapps_management/ManagingDeployDaemons.rst

@@ -17,25 +17,80 @@ Register
 
 Register Deploy Daemon (DaemonConfig).
 
-Command: ``app_api:daemon:register [--net NET] [--haproxy_password HAPROXY_PASSWORD] [--compute_device COMPUTE_DEVICE] [--set-default] [--] <name> <display-name> <accepts-deploy-id> <protocol> <host> <nextcloud_url>``
+Command: ``app_api:daemon:register [--net NET] [--haproxy_password HAPROXY_PASSWORD] [--compute_device COMPUTE_DEVICE] [--set-default] [--harp] [--harp_frp_address HARP_FRP_ADDRESS] [--harp_shared_key HARP_SHARED_KEY] [--harp_docker_socket_port HARP_DOCKER_SOCKET_PORT] [--harp_exapp_direct] [--] <name> <display-name> <accepts-deploy-id> <protocol> <host> <nextcloud_url>``
 
 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``)
-	* ``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``)
+* ``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``)
+* ``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
 *******
 
-	* ``--net [network-name]``  - ``[required]`` network name to bind docker container to (default: ``host``)
-	* ``--haproxy_password HAPROXY_PASSWORD`` - ``[optional]`` password for AppAPI Docker Socket Proxy
-	* ``--compute_device GPU`` - ``[optional]`` GPU device to expose to the daemon (e.g. ``cpu|cuda|rocm``, default: ``cpu``)
-	* ``--set-default`` - ``[optional]`` set created daemon as default for ExApps installation
+* ``--net [network-name]``  - ``[required]`` network name to bind docker container to (default: ``host``)
+* ``--haproxy_password HAPROXY_PASSWORD`` - ``[optional]`` password for AppAPI Docker Socket Proxy
+* ``--compute_device GPU`` - ``[optional]`` GPU device to expose to the daemon (e.g. ``cpu|cuda|rocm``, default: ``cpu``)
+* ``--set-default`` - ``[optional]`` set created daemon as default for ExApps installation
+* ``--harp`` - ``[optional]`` Flag to set daemon to use HaRP for all docker and exapp communication
+* ``--harp_frp_address`` - ``[optional]`` [host]:[port] of the HaRP FRP server, default host is same as HaRP host and port is 8782
+* ``--harp_shared_key`` - ``[optional]`` HaRP shared key for secure communication between HaRP and AppAPI
+* ``--harp_docker_socket_port`` - ``[optional]`` 'remotePort' of the FRP client of the remote docker socket proxy. There is one included in the harp container so this can be skipped for default setups. (default: "24000")
+* ``--harp_exapp_direct`` - ``[optional]`` Flag for the advanced setups only. Disables the FRP tunnel between ExApps and HaRP.
+
+Usage Examples
+**************
+
+* Register a HaRP deploy daemon within the ``nextcloud`` docker network, with the ``appapi-harp`` container as the host and the ``appapi-harp:8782`` as the FRP server address. This can be paired with a HaRP container running in the same network.
+
+	.. code-block:: bash
+
+		occ app_api:daemon:register harp_proxy_docker "Harp Proxy (Docker)" "docker-install" "http" "appapi-harp:8780" "http://nextcloud.local" --net nextcloud --harp --harp_frp_address "appapi-harp:8782" --harp_shared_key "some_very_secure_password" --set-default --compute_device=cuda
+
+* Register a HaRP deploy daemon with the ``localhost`` as the host and the ``localhost:8782`` as the FRP server address. This can be paired with a HaRP container running in the host network mode or has exposed the ports ``8780`` and ``8782`` to the host.
+
+	.. code-block:: bash
+
+		app_api:daemon:register harp_proxy_host "Harp Proxy (Host)" "docker-install" "http" "localhost:8780" "http://nextcloud.local" --harp --harp_frp_address "localhost:8782" --harp_shared_key "some_very_secure_password" --set-default --compute_device=cuda
+
+* Register a manual install deploy daemon with HaRP support. This can be paired with a HaRP container running in the same network. The HaRP container need not have access to a docker socket or any other ports exposed to the host. It will not create docker containers of the ExApps but will only proxy the requests to the ExApp process manually launched by the user.
+
+	.. note::
+		| The ExApp process should have a FRP Client (frpc) running in the same network as the HaRP container or should be able to connect to the ports exposed by the HaRP container.
+		| If the communication has to go without the FRP client, the ``--harp_exapp_direct`` flag should be provided. The localhost IP address is always used as the host in this case for manual deployments and ``OVERRIDE_APP_HOST`` or the ``<app_id>`` is used for ExApp deployments. Take care not to use the host network mode or the default bridge network for this.
+
+	.. code-block:: bash
+
+		app_api:daemon:register manual_install_harp "Harp Manual Install" "manual-install" "http" "appapi-harp:8780" "http://nextcloud.local" --net nextcloud --harp --harp_frp_address "appapi-harp:8782" --harp_shared_key "some_very_secure_password"
+
+* Register a Docker Socket Proxy deploy daemon with the ``nextcloud-appapi-dsp:2375`` as the host and the ``nextcloud`` docker network. This can be paired with a Docker Socket Proxy container running in the same network with the default port ``2375``.
+
+	.. code-block:: bash
+
+		app_api:daemon:register docker_install "Docker Socket Proxy" "docker-install" "http" "nextcloud-appapi-dsp:2375" "http://nextcloud.local" --net=nextcloud --set-default --compute_device=cuda
+
+* Register a manual deploy daemon with ``host.docker.internal`` as the host used to connect to the ExApps.
+
+	.. code-block:: bash
+
+		app_api:daemon:register manual_install "Manual Install" "manual-install" "http" null "http://nextcloud.local"
+
+* Register a local docker deploy daemon with the ``/var/run/docker.sock`` as the socket and the host, and the ``nextcloud`` docker network. This does not need a Docker Socket Proxy container. The compute device used by this daemon is ``CPU``.
+
+	.. code-block:: bash
+
+		app_api:daemon:register local_docker "Docker Local" "docker-install" "http" "/var/run/docker.sock" "http://nextcloud.local" --net=nextcloud
+
+* Register a local docker deploy daemon with the ``/var/run/docker.sock`` as the socket and the host, and the ``nextcloud`` docker network. This does not need a Docker Socket Proxy container. The compute device used by this daemon is ``CUDA`` (NVIDIA).
+
+	.. code-block:: bash
+
+		app_api:daemon:register local_docker "Docker Local" "docker-install" "http" "/var/run/docker.sock" "http://nextcloud.local" --net=nextcloud --set-default --compute_device=cuda
+
 
 DeployConfig
 ************
@@ -53,6 +108,11 @@ ExApp container.
 			"id": "cuda",
 			"name": "CUDA (NVIDIA)",
 		},
+		"harp": {
+			"frp_address": "localhost:8782",
+			"docker_socket_port": "24000",
+			"exapp_direct": false
+		}
 	}
 
 DeployConfig options
@@ -62,6 +122,10 @@ DeployConfig options
 	* ``nextcloud_url`` **[required]** - Nextcloud URL (e.g. ``https://nextcloud.local``)
 	* ``haproxy_password`` *[optional]* - password for AppAPI Docker Socket Proxy
 	* ``computeDevice`` *[optional]* - Compute device to attach to the daemon (e.g. ``{ "id": "cuda", "label": "CUDA (NVIDIA)" }``)
+	* ``harp`` *[optional]* - HaRP options, can be ``null`` in case of non-HaRP setups
+		* ``frp_address`` *[optional]* - [host]:[port] of the HaRP FRP server, default host is same as HaRP host and port is 8782
+		* ``docker_socket_port`` *[optional]* - 'remotePort' of the FRP client of the remote docker socket proxy. There is one included in the harp container so this can be skipped for default setups. [default: "24000"]
+		* ``exapp_direct`` *[optional]* - Flag for the advanced setups only. Disables the FRP tunnel between ExApps and HaRP.
 
 Unregister
 ----------
@@ -89,8 +153,8 @@ It is possible to register additional Deploy Daemons using the same methods as d
 Additional options
 ^^^^^^^^^^^^^^^^^^
 
-There is a possibility to add additional options to the Deploy Daemon configuration,
-which are key-value pairs.
+| There is a possibility to add additional options to the Deploy Daemon configuration, which are key-value pairs.
+| This should not be used for HaRP.
 
 Currently, the following options are available:
 

admin_manual/exapps_management/TestDeploy.rst

@@ -38,7 +38,9 @@ Possible errors:
 - Image not found (e.g. not public, no image found for your hardware architecture)
 - Image pull failed (e.g., due to network issues)
 - Image pull timeout
-- Your Docker Socket Proxy is not configured correctly and blocks access to this Docker Engine API
+- Your Docker Socket Proxy/HaRP is not configured correctly and blocks access to this Docker Engine API
+
+See ``journalctl -f -u docker.service`` for more details in systemd based systems.
 
 Container Started
 *****************
@@ -50,8 +52,9 @@ Possible errors:
 - Container failed to start with GPU support (may be missing or misconfigured)
     - For NVIDIA, refer to the `NVIDIA Docker configuration docs <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html>`_.
     - For AMD, refer to the `ROCm Docker configuration docs <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/docker.html>`_.
-- The ExApp issue during startup (e.g. not enough memory)
+- The ExApp issue during startup (e.g. not enough memory). The app would show repeated starting attempts in the logs.
 
+See ``docker logs nc_app_<app_id>`` for more details.
 
 Heartbeat
 *********
@@ -66,6 +69,7 @@ Possible errors:
 - Nextcloud can not reach the ExApp container, e.g.,
     * due to a network issue or a firewall (this should be visible in the server logs or the firewall logs)
     * due to a "http" protocol deploy daemon. In this case, the ExApp's container listens on localhost (127.0.0.1 or ::1) which might not be reachable from the Nextcloud server and you might want to listen on a different IP address. See ``OVERRIDE_APP_HOST`` in :ref:`Additional options <additional_options_list>` in the Deploy Daemon form. This issue can be identified using this command: ``lsof -i -P -n | grep LISTEN``
+- For HaRP, the main Nextcloud proxy might not be configured to redirect requests to the HaRP container correctly. See the `Configuring Your Reverse Proxy <https://github.com/nextcloud/harp?tab=readme-ov-file#configuring-your-reverse-proxy>`_ section in the HaRP readme.
 
 Init
 ****
@@ -76,6 +80,7 @@ During the init step, the ExApp may perform downloads of extra stuff required fo
 Possible errors:
 
 - Initialization failed (e.g., due to network issues or timeout)
+- ExApp not being able to reach the Nextcloud server (e.g., due to a network issue or a firewall)
 
 
 Enabled