AIO 12.9.1 Beta / HaRP migration: old ExApps left behind, GUI stuck, manual recovery steps

📑 How to
, ,
1

AIO 12.9.1 Beta / HaRP migration: old ExApps left behind, GUI stuck, manual recovery steps

Hi,

I want to share a recovery guide for a problem I hit after updating to Nextcloud AIO 12.9.1 Beta on the Beta channel, where I switched from Docker Proxy for ExApps to HaRP.

In my case, I previously had these ExApps deployed through the old Docker Proxy:

  • Nextcloud Context Agent

  • Assistant Talk Bot

After the update, both old ExApp containers were still present and running in Docker/Portainer, but in the Nextcloud GUI the apps were stuck in a broken state.

Problem symptoms

What I saw:

  • Deploy and Enable was inactive in the GUI

  • Docker Proxy showed as unavailable

  • the apps could not be properly disabled, re-deployed, or migrated from the GUI

  • the old containers were still visible and running in Docker/Portainer

  • AppAPI was no longer properly controlling them

From the AppAPI side, the state was inconsistent:

  • the old deploy daemon docker_aio was still registered and pointing to nextcloud-aio-docker-socket-proxy:2375

  • app_api:app:list showed no registered ExApps

  • but the old ExApp containers were still running in Docker

So from the user perspective, the system looked half-migrated:

  • old ExApps were still running

  • the old daemon was still registered

  • the GUI could not manage the apps anymore

My environment

  • Nextcloud AIO 12.9.1 Beta

  • Beta channel

  • migration from Docker Proxy for ExApps to HaRP

  • affected ExApps:

    • Nextcloud Context Agent

    • Assistant Talk Bot

Important note before starting

In my case, during the recovery I also ran into an authentication problem because I had overwritten the shared key shown in the GUI.
So if Check connection fails with 401 Unauthorized, verify that the HaRP shared key in the GUI matches the actual HP_SHARED_KEY inside the running nextcloud-aio-harp container.

That part may have been user error on my side, not necessarily a template bug.

Step 1 — Check current AppAPI daemon state

Run:

sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ app_api:daemon:list

If you are affected by the same issue, you may still see the old daemon, for example:

  • docker_aio

  • pointing to nextcloud-aio-docker-socket-proxy:2375

Step 2 — Check AppAPI ExApps list

Run:

sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ app_api:app:list

In my case, this returned no registered ExApps even though the old ExApp containers were still running in Docker.

Step 3 — Unregister the old Docker Proxy daemon

Run:

sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ app_api:daemon:unregister docker_aio

Then verify:

sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ app_api:daemon:list

At this point I got:

No registered daemon configs.

Step 4 — Verify that HaRP is running

Run:

sudo docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}" | grep -Ei 'harp|appapi'

In my case I saw:

  • nextcloud-aio-harp

  • status Up ... (healthy)

You can also check the broader AIO stack:

sudo docker ps --format "table {{.Names}}\t{{.Status}}" | grep -Ei 'nextcloud-aio|nc_app_'

This helped confirm:

  • HaRP was healthy

  • the old ExApp containers were still present as:

    • nc_app_context_agent

    • nc_app_talk_bot_ai

Step 5 — Stop and remove the old leftover ExApp containers

Run:

sudo docker stop nc_app_context_agent nc_app_talk_bot_ai

Then:

sudo docker rm nc_app_context_agent nc_app_talk_bot_ai

Verify:

sudo docker ps -a --format "table {{.Names}}\t{{.Status}}" | grep -Ei 'nc_app_context_agent|nc_app_talk_bot_ai'

This should return nothing.

Step 6 — Use the correct AppAPI template

Go to:

Administration settings → AppAPI → Register Deploy Daemon

For Nextcloud AIO, use:

  • HaRP All-in-One

Do not use:

  • HaRP Proxy (Host)

This was confusing at first because the first visible/default-looking option I saw was the host-style template, while the correct choice for AIO was HaRP All-in-One.

Step 7 — If Check connection fails, verify the shared key

If Check connection fails, especially with a 401 Unauthorized error in the logs, verify the actual HaRP shared key from Docker.

Run:

sudo docker inspect nextcloud-aio-harp --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^HP_SHARED_KEY='

Example output:

HP_SHARED_KEY=ff4ad88fcebc0ccb1a8e147eda0ba27824104ecafc30a799

Make sure the value in the AppAPI GUI field HaRP shared key matches this exactly.

In my case, Check connection only passed after I used the actual key from the running nextcloud-aio-harp container.

Step 8 — Register the new HaRP daemon

Once Check connection passes, click:

  • Register

Then verify with:

sudo docker exec --user www-data -it nextcloud-aio-nextcloud php occ app_api:daemon:list

In my case the correct final state was:

Registered ExApp daemon configs:
+-----+----------+-----------------+----------------+----------+-------------------------+-------------------------------+---------+-------------------------+-------------------------+
| Def | Name     | Display name    | Deploy ID      | Protocol | Host                    | NC Url                        | Is HaRP | HaRP FRP Address        | HaRP Docker Socket Port |
+-----+----------+-----------------+----------------+----------+-------------------------+-------------------------------+---------+-------------------------+-------------------------+
| *   | harp_aio | HaRP All-in-One | docker-install | http     | nextcloud-aio-harp:8780 | https://your-domain.example   | yes     | nextcloud-aio-harp:8782 | 24000                   |
+-----+----------+-----------------+----------------+----------+-------------------------+-------------------------------+---------+-------------------------+-------------------------+

Step 9 — Redeploy the ExApps from the GUI

After the new HaRP daemon is registered correctly, go back to the ExApps and redeploy them from the GUI.

In my case:

  • Assistant Talk Bot deployed correctly and worked in Talk

  • Nextcloud Context Agent deployed correctly and the container reached Healthy

What the issue looked like in practice

For me, the migration ended up requiring manual cleanup because after the AIO update:

  • the old Docker Proxy daemon was still registered

  • the old ExApp containers were still running

  • AppAPI no longer listed the ExApps

  • the GUI could not manage them anymore

  • manual cleanup was needed before HaRP-based deployment became usable again

Suggestion for other users

If you hit a similar issue after the Docker Proxy → HaRP transition in AIO:

  1. check app_api:daemon:list

  2. check app_api:app:list

  3. unregister the old docker_aio daemon

  4. verify nextcloud-aio-harp is healthy

  5. remove orphaned nc_app_* containers

  6. use HaRP All-in-One

  7. verify the HaRP shared key

  8. register the new daemon

  9. redeploy the ExApps from the GUI

Final note

Everything is working again now, but the transition was fully manual in my case.

I am posting this in case other AIO users run into the same half-migrated state after the move from Docker Proxy to HaRP.

5 Likes
How to migrate Nextcloud AIO from deprecated Docker Socket Proxy to HaRP