[GUIDE] Nextcloud Assistant (Context Chat) on TrueNAS SCALE - Docker setup (No K3s)

Apps and Virtualization
, , ,
1

Body: Hi everyone, I’ve successfully integrated Nextcloud Assistant with local embeddings on TrueNAS SCALE (Docker-only). Since SCALE is moving away from K8s, I wanted to share a working setup for AppAPI and Context Chat.

1. Prerequisites in Nextcloud Install these apps: AppAPI, Context Chat, Context Chat Backend, and Context Agent.

2. Setup docker-socket-proxy Create a Custom App with image tecnativa/docker-socket-proxy:latest.

Mount: /var/run/docker.sock to /var/run/docker.sock.

Port: 2375.

ENV Variables: CONTAINERS=1, NETWORKS=1, VOLUMES=1, IMAGES=1, POST=1, PING=1, INFO=1.

3. The “Magic” Connectivity Step You must manually connect the proxy to the Nextcloud network so they can talk: docker network connect ix-nextcloud_default ix-docker-socket-proxy_default

4. Register Daemon in Nextcloud AppAPI

Host: docker-socket-proxy:2375.

Network: ix-nextcloud_default.

5. Deploy Backend Go to Nextcloud Apps and click “Deploy and Enable” on Context Chat Backend. Wait a few minutes for the model to load into RAM.

6. Force Indexing If the Vector DB stays at 0, run the worker manually in the Nextcloud container shell: docker exec -u 33 -it ix-nextcloud-nextcloud-1 sh -lc 'php -f /var/www/html/occ background-job:worker -t 900'

1 Like
2

Hey, thanks for the guide! This gets rid of the nasty Deploy Daemon error in Overview.

I followed your instructions, but I tried to skip the manual network connection step. Seemed like too much trouble just for the sake of the hostname. This works for me as well:

image
image589×624 21.1 KB

image
image588×692 30.6 KB

1 Like
3

That setup works because it talks to Docker over the TCP API (port 2375), which exposes the Docker daemon directly on the network. It feels simpler since there’s no socket permission handling or proxy layer.

The trade-off is that port 2375 effectively grants full control over Docker to anything that can reach it. From Docker’s perspective, that’s equivalent to root-level access to container management on the host.

Nextcloud’s AppAPI documentation recommends using a Docker Socket Proxy instead of exposing the daemon directly. The goal isn’t complexity for its own sake — it’s about reducing the attack surface and restricting which API calls external apps are allowed to make.

Both approaches work:

  • TCP Docker API → simpler to wire up

  • Socket proxy → controlled, safer, and easier to keep long-term

We chose the proxy route because this is a long-lived system and we prefer a setup that survives updates without reopening Docker to the LAN.

References (copy & fix spaces):
Note: links are written with spaces on purpose so the forum doesn’t auto-convert them into clickable URLs. Just remove the spaces when copying.

docs . nextcloud . com / server / latest / admin_manual / exapps_management / AppAPIAndExternalApps . html
docs . docker . com / engine / security / #docker-daemon-attack-surface
github . com / nextcloud / docker-socket-proxy

4

Docker over the TCP API is not exposed on TrueNAS Scale. It’s still tecnativa/docker-socket-proxy custom app, but I’ve just realized it depends on how you set 2375 port binding, if it’s exposed to host, it’s avaiable as a service to all apps.

Your command makes sense when port bind mode is inter-container communication, which probably is better choice I didn’t make :smiley:

5

You’re basically right, and I think we’re just looking at it from two slightly different angles.

So in short:

• You’re right about the default state on TrueNAS SCALE
• We’re right about the architecture and security choice for this kind of setup

TrueNAS SCALE does not expose the Docker TCP API by default, and that’s a good thing.
But once you start binding port 2375 or exposing it via a service, it effectively becomes a network service available to anything that can reach it.

For our setup, we intentionally avoided that and stayed with socket / socket-proxy style access.

Why we consider this the more “enterprise-safe” route:

• Docker daemon is never exposed over the network
• Follows least-privilege principle (proxy can restrict allowed API calls)
• Matches how AppAPI is designed to be used long-term
• More update-proof (no need to modify dockerd startup config or maintain custom daemon flags)

Both approaches work technically.
TCP API is simpler to set up.
Socket / proxy is usually safer and more future-proof for long-lived systems.

Since this box is meant to run long-term and survive upgrades, we preferred the proxy approach.

And yeah — if someone binds 2375 only for inter-container communication and keeps it off LAN, that’s already a big improvement compared to exposing it to the whole network.

6

There may be a better and easier way to connect the proxy to another application. Rather than connecting the two networks, you can instruct the app to join an existing network directly from the GUI. It should be perfectly fine right?

image
image452×729 14.1 KB

1 Like
7

See you now with version 33 - Winter

8

Hi Pavel, can you help with an update to this guide and help us understand what the exact steps are, please?

I’m trying to do this and your post is the closest thing to a “guide” out there.

Thanks

9

Hi Vyker,

Happy to help! I just went through the full setup again today on Nextcloud 33 + TrueNAS SCALE (Docker), so here’s the updated step-by-step:

1. Prerequisites in Nextcloud
Install these apps: AppAPI, Context Chat, Context Chat Backend, Context Agent.

2. Setup docker-socket-proxy (Custom App in TrueNAS)

  • Image: tecnativa/docker-socket-proxy:latest
  • Mount: /var/run/docker.sock → /var/run/docker.sock
  • Port: 2375 (inter-container only, do NOT expose to host)
  • ENV variables: CONTAINERS=1, NETWORKS=1, VOLUMES=1, IMAGES=1, POST=1, PING=1, INFO=1

3. The critical network step
The proxy container starts in its own network. You must connect it to the Nextcloud network:

docker network connect ix-nextcloud_default nc-docker-socket-proxy

(verify your network name with: docker network ls | grep nextcloud)

4. Register Daemon in Nextcloud AppAPI

  • Template: Docker Socket Proxy
  • Host: nc-docker-socket-proxy:2375 ← no http:// prefix!
  • Network: ix-nextcloud_default
  • Enable HTTPS: OFF
  • Enable HaRP: OFF

:warning: Important gotcha: When you click “Check connection”, AppAPI spins up a temporary nc_app_test-deploy container. This container also needs to be in the right network. Since the socket-proxy is now in ix-nextcloud_default, and test-deploy also starts in ix-nextcloud_default, it should work automatically.

5. Deploy Backend
Go to Nextcloud Apps → find Context Chat Backend → “Deploy and Enable”. Wait a few minutes for the model to load into RAM.

6. Force indexing (if Vector DB stays at 0)

docker exec -u 33 -it ix-nextcloud-nextcloud-1 sh -lc 'php -f /var/www/html/occ background-job:worker -t 900'

The most common failure points I’ve seen:

  1. Host field must NOT include http:// — just nc-docker-socket-proxy:2375
  2. The socket-proxy must be in the same Docker network as Nextcloud
  3. The container name in your setup might differ — check with docker ps | grep socket

Hope this helps!

10

Update after testing on Nextcloud 33 + TrueNAS SCALE (May 2026):

A few critical things I missed in the original guide:

1. Host field must NOT include http://
In the AppAPI daemon registration, the Host field expects only:

nc-docker-socket-proxy:2375

Not http://nc-docker-socket-proxy:2375. AppAPI adds the protocol itself based on the Protocol field.

2. POST=1 is required
The socket-proxy needs POST=1 to pull Docker images. Without it you get 403 Forbidden when AppAPI tries to deploy ExApps.

3. Network setup is the trickiest part
On TrueNAS SCALE with the default Nextcloud app, the Nextcloud container runs in ix-nextcloud_ix-internal-nextcloud-net, NOT ix-nextcloud_default. The socket-proxy must be in the same network as Nextcloud.

The permanent fix is to create the socket-proxy container with both networks:

docker run -d \
  --name nc-docker-socket-proxy \
  --network ix-nextcloud_ix-internal-nextcloud-net \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e CONTAINERS=1 -e NETWORKS=1 -e VOLUMES=1 \
  -e IMAGES=1 -e POST=1 -e PING=1 \
  -e INFO=1 -e EVENTS=1 \
  --restart unless-stopped \
  tecnativa/docker-socket-proxy:latest

docker network connect ix-nextcloud_default nc-docker-socket-proxy

4. ExApp containers also need the right network
After each ExApp deployment (Context Chat Backend, Context Agent), the new container lands in ix-nextcloud_default but needs to be in ix-nextcloud_ix-internal-nextcloud-net:

docker network connect ix-nextcloud_ix-internal-nextcloud-net nc_app_context_chat_backend
docker network connect ix-nextcloud_ix-internal-nextcloud-net nc_app_context_agent

5. AppAPI daemon network setting
Set the Docker network in the daemon config to:

ix-nextcloud_ix-internal-nextcloud-net

Verify your actual network names with:

docker network ls | grep nextcloud
docker inspect ix-nextcloud-nextcloud-1 --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}}{{"\n"}}{{end}}'

Once everything is connected correctly, indexing starts automatically and you should see documents appearing in the Vector DB within minutes.