Fix NGINX example in README.md and others as applicable... #57
Description
How to use GitHub
- Please use the 👍 reaction to show that you are affected by the same issue.
- Please don't comment if you have no relevant information to add. It's just extra noise for everyone subscribed to this issue.
- Subscribe to receive notifications on status change and new comments.
Steps to reproduce
Configuring Your Reverse Proxy
HaRP requires your reverse proxy to forward traffic from your public domain (e.g., nextcloud.com/exapps/) to the HaRP container’s HP_EXAPPS_ADDRESS. Below are sample configurations for NGINX, Caddy, and Traefik.
Using NGINX Configuration from README.md
https://github.com/nextcloud/HaRP/blob/079eef325419b3d035078cdeff76f02491339c8f/README.md
Having added the following lines to the NGINX configuration for the nextcloud site:
location /exapps/ {
proxy_pass http://127.0.0.1:8780;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
docker logs -f appapi-harp
<134>Oct 20 13:25:29 haproxy[29]: 172.17.0.1:45160 [20/Oct/2025:13:25:29.990] ex_apps ex_apps/<NOSRV> 1/-1/-1/-1/1 404 92 - - LR-- 2/2/0/0/0 0/0 "GET /test-deploy/heartbeat HTTP/1.0"
[2025-10-20T13:25:30+0000] [DEBUG] [88fc0302] Incoming `notify` frame from HAProxy
[2025-10-20T13:25:30+0000] [INFO] [88fc0302] Received request on key 'exapps_msg'
[2025-10-20T13:25:30+0000] [INFO] [88fc0302] Found 1 matching handlers, awaiting response...
[2025-10-20T13:25:30+0000] [DEBUG] Incoming request to ExApp: path=/test-deploy/heartbeat, headers=host: bmi-cloud.ops.vwrls.ca
x-real-ip: ****
x-forwarded-for: ****
x-forwarded-proto: https
accept: application/json
content-type: application/json
aa-version: 32.0.0
ex-app-id: test-deploy
ex-app-version: 1.2.0
authorization-app-api: ****
aa-request-id: CLI
harp-shared-key: ****
ex-app-port: 23000
ex-app-host: 127.0.0.1
user-agent: Nextcloud Server Crawler
accept-encoding: gzip
, ip=127.0.0.1
[2025-10-20T13:25:30+0000] [ERROR] Invalid request path, cannot find AppID: /test-deploy/heartbeat
[2025-10-20T13:25:30+0000] [DEBUG] Recorded failure for IP 127.0.0.1. Failures in window: 2
[2025-10-20T13:25:30+0000] [INFO] [88fc0302] Responding with combined payload of 15 bytes
--AND--
While docker run includes: -e HP_TRUSTED_PROXY_IPS="127.0.0.0/8"
<134>Oct 20 13:55:02 haproxy[29]: 127.0.0.1:39966 [20/Oct/2025:13:55:02.117] ex_apps ex_apps/<NOSRV> -1/-1/-1/-1/1 -1 0 - - PR-- 2/2/0/0/0 0/0 "GET /test-deploy/heartbeat HTTP/1.0"
[2025-10-20T13:55:03+0000] [DEBUG] [e10b74b8] Incoming `notify` frame from HAProxy
[2025-10-20T13:55:03+0000] [INFO] [e10b74b8] Received request on key 'exapps_msg'
[2025-10-20T13:55:03+0000] [INFO] [e10b74b8] Found 1 matching handlers, awaiting response...
[2025-10-20T13:55:03+0000] [DEBUG] Incoming request to ExApp: path=/test-deploy/heartbeat, headers=host: bmi-cloud.ops.vwrls.ca
x-real-ip: ****
x-forwarded-for: ****
x-forwarded-proto: https
accept: application/json
content-type: application/json
aa-version: 32.0.0
ex-app-id: test-deploy
ex-app-version: 1.2.0
authorization-app-api: ****
aa-request-id: CLI
harp-shared-key: ****
ex-app-port: 23000
ex-app-host: 127.0.0.1
user-agent: Nextcloud Server Crawler
accept-encoding: gzip
, ip=127.0.0.1
[2025-10-20T13:55:03+0000] [WARNING] IP 127.0.0.1 is banned due to excessive failed attempts.
[2025-10-20T13:55:03+0000] [INFO] [e10b74b8] Responding with combined payload of 17 bytes
Expected behaviour
AppID is correctly parsed from url ?
Heartbeats are correctly received, stored, and distributed
When the client IP is inside the trusted proxy environment variable network the ip address from the x-real-ip or x-forwarded-for headers supersede the IP address for blacklist and other processing logic.
Correct documentation in README.md for NGINX:
location /exapps/ {
proxy_pass http://127.0.0.1:8780/exapps/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
Hint in container logs
<134>Oct 20 14:50:05 haproxy[29]: 127.0.0.1:59840 [20/Oct/2025:14:50:03.176] ex_apps nextcloud_control_backend/nextcloud_control 1/0/0/2017/2018 200 217 - - ---- 1/1/0/0/0 0/0 "POST /exapps/app_api/docker/exapp/wait_for_start HTTP/1.1"
[2025-10-20T14:50:05+0000] [DEBUG] [e10b74b8] Incoming `notify` frame from HAProxy
[2025-10-20T14:50:05+0000] [INFO] [e10b74b8] Received request on key 'exapps_msg'
[2025-10-20T14:50:05+0000] [INFO] [e10b74b8] Found 1 matching handlers, awaiting response...
[2025-10-20T14:50:05+0000] [DEBUG] Incoming request to ExApp: path=/exapps/app_api/v1.41/containers/nc_app_test-deploy/json, headers=host: localhost:8780
harp-shared-key: ****
docker-engine-port: 24001
user-agent: GuzzleHttp/7
authorization: Basic ****
, ip=127.0.0.1
[2025-10-20T14:50:05+0000] [DEBUG] Request from AppAPI received: /v1.41/containers/nc_app_test-deploy/json
[2025-10-20T14:50:05+0000] [INFO] [e10b74b8] Responding with combined payload of 111 bytes
Actual behaviour
AppID is not recognized in request url
IP address in HP_TRUSTED_PROXY_IPS network range is blacklisted
Incorrect documentation in README.md for NGINX:
https://github.com/nextcloud/HaRP/blob/079eef325419b3d035078cdeff76f02491339c8f/README.md
location /exapps/ {
proxy_pass http://127.0.0.1:8780;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
Server configuration
Web server: Nginx
Database: PostgreSQL
PHP version: 8.4
Nextcloud version: 32.0.0
Browser name: Chromium
Browser version: 138.0.7204.157
Operating system: Debian 12