AppAPI: OVERRIDE_APP_HOST inaccessible via any official interface, causing APP_HOST=127.0.0.1 on remote Docker deployments and breaking Ex-App heartbeat

[techsurrusr]

AppAPI: OVERRIDE_APP_HOST inaccessible via any official interface, causing APP_HOST=127.0.0.1 on remote Docker deployments and breaking Ex-App heartbeat

Running Nextcloud 33.0.3 with AppAPI 33.0.0, and have fully confirmed a bug where deploying Ex-Apps to a remote Docker host always results in APP_HOST=127.0.0.1 being passed to the container — making it impossible for Nextcloud to reach the container for the heartbeat check, causing all Ex-App deployments to fail silently.

The setup is a standard production configuration: Nextcloud runs on a dedicated LXC container, and the Docker daemon runs on a separate host on the same internal network. This is a common architecture for self-hosted environments where Docker workloads are isolated from the application server.

The Problem

When AppAPI deploys an Ex-App container using docker-install with --net host on a remote Docker host, it hardcodes APP_HOST=127.0.0.1 in the container's environment. The container then binds Uvicorn exclusively to 127.0.0.1:23000 — unreachable from the Nextcloud server — causing the heartbeat check to fail and the deployment to roll back with ExApp heartbeat check failed.

The root cause is in DockerActions.php at line 1171:

sprintf('APP_HOST=%s', $params['host']),

When using host networking on a remote Docker host, $params['host'] resolves to the loopback address. The container starts correctly, pulls the image, runs — but binds only on localhost and is unreachable from Nextcloud.

The Hidden Override

OVERRIDE_APP_HOST exists in the AppAPI source code and is explicitly checked at lines 1212-1218 of DockerActions.php:

if (isset($deployConfig['additional_options']['OVERRIDE_APP_HOST']) &&
    $deployConfig['additional_options']['OVERRIDE_APP_HOST'] !== ''
) {
    if (!in_array($deployConfig['additional_options']['OVERRIDE_APP_HOST'], $wideNetworkAddresses)) {
        // use OVERRIDE_APP_HOST value
    }
}

This mechanism exists and works correctly — but it is completely inaccessible through any official interface:

• ❌ Not exposed in the Web UI daemon registration form
• ❌ Not available as a parameter in occ app_api:daemon:register
• ❌ Not documented anywhere in the AppAPI documentation
• ❌ The same pattern exists in HarpService.php and ManualActions.php — all unreachable

The only way to set it is by directly manipulating the database:

UPDATE oc_ex_apps_daemons
SET deploy_config = JSON_SET(
  deploy_config,
  '$.additional_options',
  JSON_OBJECT('OVERRIDE_APP_HOST', '<docker_host_ip>')
)
WHERE name = '<daemon_name>';

Once set this way, deployments succeed immediately — APP_HOST is correctly set to the Docker host IP and the heartbeat check passes.

Impact

This effectively makes AppAPI non-functional for any deployment where Docker runs on a separate host from Nextcloud — which is a common and recommended production architecture. The failure mode is particularly confusing because:

1. The connection check reports "Daemon connection successful"
2. The image pull succeeds
3. The container starts and reports healthy
4. The deployment silently fails at the heartbeat step with no actionable error message

There is no indication in the UI or logs that OVERRIDE_APP_HOST exists or needs to be set.

Proposed Fix

OVERRIDE_APP_HOST should be exposed through official interfaces. At minimum one of the following:

Option A — Add to occ app_api:daemon:register:

--override_app_host=OVERRIDE_APP_HOST   Override the APP_HOST passed to deployed
                                         Ex-App containers. Required when Docker
                                         runs on a separate host from Nextcloud.

Option B — Add to the Web UI daemon registration form under "Deploy options" as an optional field labeled "ExApp host override (APP_HOST)" with appropriate help text explaining when it is needed.

Option C — Auto-detect remote hosts: When the daemon host is not localhost, 127.0.0.1, or a Unix socket path, AppAPI should automatically resolve and use the daemon's hostname/IP as APP_HOST rather than defaulting to loopback.

Option C is the most user-friendly as it requires no manual intervention for the common case.

Environment

• Nextcloud: 33.0.3
• AppAPI: 33.0.0
• Docker host: separate from Nextcloud, internal network only
• DSP image: ghcr.io/nextcloud/nextcloud-appapi-dsp:latest
• Deployment method: docker-install, --net host

Kind Regards,

Kim @ njordium.com

[oleksandr-nc]

@techsurrusr thanks for the report.

Could you whenever you have time describe the setup you have?

We'd like to move away from using OVERRIDE_APP_HOST altogether, so I'm really curious about what current setups require it.

With the advent of HaRP and reverse tunneling(FRP), is there any situation where OVERRIDE_APP_HOST is still necessary?

[khnjrdm]

Thanks for following up. Happy to describe our setup in detail.

Environment:

• Nextcloud 33.0.3 running on a dedicated Ubuntu 24.04 LXC container behind an Apache reverse proxy
• Docker host on a separate Ubuntu 24.04 LXC container on the same internal /24 subnet
• Both LXCs run on a Proxmox VE cluster on-premises
• The Docker host already runs other containers (Talk HPB, Talk Recording), so pre-existing, not deployed specifically for AppAPI
• Network between the two hosts is internal only, no public exposure of Docker ports

With docker-install and --net host, AppAPI hardcodes APP_HOST=127.0.0.1 in the deployed Ex-App container environment. The container binds Uvicorn to 127.0.0.1:23000 which is unreachable from the Nextcloud LXC. OVERRIDE_APP_HOST fixed this by making the container bind on the Docker host's actual IP, making it reachable from Nextcloud.

I did attempt HaRP during setup but were unable to get it working correctly on a remote Docker host — HaRP never successfully activated inside the DSP container. We reverted to the plain DSP setup without HaRP to get things operational, which is where OVERRIDE_APP_HOST became necessary. HaRP is something we intend to revisit.

If the goal is to deprecate OVERRIDE_APP_HOST, the most impactful improvements would be:

• Auto-detect remote hosts so when the daemon host is not localhost/socket, automatically use the daemon hostname/IP as APP_HOST instead of 127.0.0.1
• Document HaRP for remote Docker setups with correct environment variable names and port requirements
• Expose OVERRIDE_APP_HOST in the Web UI and occ as a transitional measure while HaRP adoption grows