Dockerode Integration#

Homepage uses dockerode (^5.0.0) as its Docker API client to connect to the Docker daemon — primarily via the Unix socket /var/run/docker.sock on Linux 1. All Docker-related features (container status, stats, and service discovery from labels) go through this single library.

Architecture#

Connection arguments are built centrally in src/utils/config/docker.js. Key behavior:

• Default (Linux): { socketPath: "/var/run/docker.sock" } 2
• Default (Windows/macOS): { host: "127.0.0.1" } 3
• Named servers (via docker.yaml): Supports socket, host, port, protocol, headers, and TLS options (ca, cert, key) 4
• Swarm mode is toggled per server via the swarm flag in docker.yaml 5

Dockerode is instantiated with new Docker(getDockerArguments(server).conn) in three places:

A new dockerode connection is opened on each request — there is no persistent connection pool.

v4 → v5 Migration (June 2026)#

PR #6736 (merged 2026-06-03) bumped dockerode from 4.0.10 to 5.0.0. Changes in the upstream release:

• Dropped the uuid package dependency
• Bumped minimum Node.js version requirement
• Upgraded protobufjs from 7.3.2 to 7.5.5 (used internally for gRPC-style features)

No Homepage application code was modified — only package.json changed 6.

Known Issue: Synology EACCES on /var/run/docker.sock#

Symptom: Error: connect EACCES /var/run/docker.sock on every dashboard load, first appearing around v2.3.0, on Synology NAS hosts running Container Manager 7.

What was ruled out:

• Socket permissions are normal (srw-rw---- 1 root root) 7
• The Homepage container runs as root (uid=0) — confirmed via docker exec homepage id 7
• Other containers (e.g., Uptime Kuma) access the same socket without issue 7
• The docker.yaml config and compose file are valid 7

Root cause hypothesis: dockerode v5 changed docker-modem internals that alter how the Unix socket connect() syscall is issued. This appears to interact with Synology Container Manager's per-image confinement profiles (AppArmor/seccomp) differently from v4 7.

Why v2.3.0 surfaced it more visibly: v2.3.0 replaced per-service endpoints (/api/docker/status/[...service], /api/docker/stats/[...service]) with bulk endpoints (/api/docker/statuses, /api/docker/stats) that query Docker on every dashboard load, making the failure impossible to miss 7.

Workarounds#

1. Use a Docker socket proxy (recommended) — avoids direct socket access entirely. See the Homepage docs on socket proxies.

2. Try a pre-v5 image — a v2.1.x image (released before the June 2026 dockerode bump) can help confirm whether the failure is v5-specific in your environment 7. Note: running old images is not a long-term solution.

3. Check for Synology socket path changes — Some DSM versions relocate the socket (e.g., to /var/packages/ContainerManager/var/docker.sock), leaving a stale mount behind. Verify with ls -l /var/run/docker.sock on the host 7.

Key Source References#