bug: HOSTNAME inherits the host's name under network_mode: host, breaking container self-inspection

[jrehm]

Symptom
After enabling the signalk-container (Container Manager) plugin on a standard HALOS deployment, any plugin that uses signalk-container's resolveHostPath() API fails to resolve paths. The signalk-charts-provider-simple plugin surfaces this as:

"Chart conversion paths are not reachable from the container runtime. Move the chart directory under app.getDataDirPath() or extend the SignalK container bind/volume to cover it."

Environment
Standard HALOS deployment (as of May 2026): SignalK Server v2.27.0, node 24.x, signalk-container v1.4.0, signalk-charts-provider-simple v2.0.0-beta.1

---

There are three separate gaps in the default HALOS SignalK container configuration that all need to be addressed for the Container Manager plugin to work. They form a dependency chain — each one is a prerequisite for the next.

Gap 1: Docker socket is inaccessible — missing group membership

The /run:/run mount already makes /var/run/docker.sock visible inside the container (since /var/run → /run). However, the socket is owned by the docker group (GID 114 on a standard HALOS host), and the node user running SignalK is not a member of that group. Any attempt by a plugin to connect to the socket fails with permission denied.

Workaround: Add GID 114 to group_add in the SignalK docker-compose.yml:

group_add:
  - '960'   # pre-existing (serial devices)
  - '114'   # docker group — socket access

Note: GID 114 is the docker group GID on a standard HALOS/Debian install. Verify with getent group docker on the host if different.

Gap 2: Docker CLI binary is not available inside the container

The signalk-container plugin detects the container runtime by executing docker --version as a subprocess. The Docker socket alone is not sufficient — the CLI binary must also be present. The HALOS SignalK container image (Ubuntu 24.04-based) does not include Docker.

Workaround: Bind-mount the host's Docker CLI binary into the container read-only:

volumes:
  - /run:/run
  - /usr/bin/docker:/usr/bin/docker:ro

The host binary works inside the container because it only depends on libc.so.6, which is present in the Ubuntu 24.04 image.

Gap 3: HOSTNAME inherits the host's name under network_mode: host, breaking container self-inspection

The SignalK container uses network_mode: host. In this mode, Docker sets $HOSTNAME inside the container to the host's hostname (e.g. halos) rather than the container name (signalk-server). The signalk-container plugin's resolveHostPath() calls docker inspect $HOSTNAME to discover its own mounts — with host networking this fails with Error: No such object: halos, causing the function to return null for every path.

Workaround: Set HOSTNAME explicitly in the container environment:

environment:
  - HOSTNAME=signalk-server

This overrides the inherited host hostname without touching the UTS namespace, which is safe with host networking.

---

Suggested fix

All three should be added to the HALOS SignalK container template:

environment:
  - HOSTNAME=signalk-server   # required for container self-inspection under network_mode: host

volumes:
  - /run:/run
  - /usr/bin/docker:/usr/bin/docker:ro   # Docker CLI for signalk-container plugin

group_add:
  - '960'
  - '114'   # docker group GID — socket access for signalk-container plugin

Verification

All three workarounds confirmed on HALPI2 (HALOS). After applying:

# Gap 1 — socket access
docker inspect signalk-server --format '{{json .HostConfig.GroupAdd}}'
# expects: ["960","114"]

# Gap 2 — CLI binary
docker exec signalk-server docker --version
# expects: Docker version 26.x.x...

# Gap 3 — HOSTNAME
docker exec signalk-server sh -c 'echo $HOSTNAME'
# expects: signalk-server

After all three are in place, resolveHostPath() returns correct paths and S-57 ENC chart conversion completes successfully.

Note: All three workarounds must be manually reapplied after any HALOS update that regenerates the SignalK docker-compose.yml.