From c65fac51bb9247a9eca541e12ba7bc4e5d61a946 Mon Sep 17 00:00:00 2001 From: Oleksandr Piskun Date: Mon, 28 Sep 2026 14:23:17 +0000 Subject: [PATCH] docs(exapps): warn to generate a unique HaRP shared key Signed-off-by: Oleksandr Piskun --- .../exapps_management/AppAPIAndExternalApps.rst | 2 +- .../exapps_management/DeployConfigurations.rst | 11 +++++++++++ .../exapps_management/ManagingDeployDaemons.rst | 4 +++- 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/admin_manual/exapps_management/AppAPIAndExternalApps.rst b/admin_manual/exapps_management/AppAPIAndExternalApps.rst index c281a01481f..03234de7dd9 100644 --- a/admin_manual/exapps_management/AppAPIAndExternalApps.rst +++ b/admin_manual/exapps_management/AppAPIAndExternalApps.rst @@ -42,7 +42,7 @@ 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 `. -1. Setup a Docker container called `HaRP `_ 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``. +1. Setup a Docker container called `HaRP `_ 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``, and :ref:`generate your own shared key ` instead of using the example value. 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``. diff --git a/admin_manual/exapps_management/DeployConfigurations.rst b/admin_manual/exapps_management/DeployConfigurations.rst index c93d5b64e5b..72a6426ab21 100644 --- a/admin_manual/exapps_management/DeployConfigurations.rst +++ b/admin_manual/exapps_management/DeployConfigurations.rst @@ -49,6 +49,17 @@ In any of the cases, the following connections should succeed: * ExApp -> HaRP container (on port 8782) * ExApp -> Nextcloud (through proxy or directly as the ``Nextcloud URL`` in the daemon config dictates) +.. _ai-app_api_harp-shared-key: + +.. warning:: + + The examples below use ``some_very_secure_password`` as the HaRP shared key. This is only a placeholder: generate + your own random key for every installation, for example with ``openssl rand -hex 32``. + + Use the same key for ``HP_SHARED_KEY`` of the HaRP container, the **HaRP shared key** field of the deploy daemon + and, for a remote Docker host, ``metadatas.token`` in ``frpc.toml``. Anyone who knows the key can talk to HaRP the + way Nextcloud does, including managing ExApp containers on the Docker host, so keep it secret. + .. _ai-app_api_nc-harp-baremetal: Nextcloud and Docker on the same host - with Nextcloud bare metal diff --git a/admin_manual/exapps_management/ManagingDeployDaemons.rst b/admin_manual/exapps_management/ManagingDeployDaemons.rst index b3712575cc6..bd1c78c0228 100644 --- a/admin_manual/exapps_management/ManagingDeployDaemons.rst +++ b/admin_manual/exapps_management/ManagingDeployDaemons.rst @@ -38,7 +38,9 @@ Options * ``--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_shared_key`` - ``[optional]`` HaRP shared key for secure communication between HaRP and AppAPI. It must + match ``HP_SHARED_KEY`` of the HaRP container. The ``some_very_secure_password`` value in the examples below is only + a placeholder, see :ref:`HaRP shared key `. * ``--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.