Dockge widget API research
Verified 2026-10-29 against louislam/dockge master. API is internal Socket.IO 4, rather than a documented REST dashboard endpoint. Upstream uses socket.io-client ~4.8.1 (package).
Important result: total containers is not exposed
Dockge’s reviewed standard events can provide running containers, but cannot accurately enumerate all existing containers including stopped containers. Neither counting stacks nor parsing Compose YAML supplies that total. Do not implement misleading total-container stats from those sources.
dockerStatsexecutesdocker stats --format json --no-streamwithout--all. It returns running container rows only. Server method, Docker stats reference.serviceStatusListexecutesdocker compose ps --format jsonwithout--all. It groups returned containers by service, using statusHealth || State. It does not enumerate all stopped containers. Stack method, Compose ps reference.stackListreducesdocker compose ls --allstatus strings such asexited(1), running(1)to a single stack status code, losing the embedded counts. It also omits standalone non-Compose containers and may omit Dockge’s own unmanaged stack. Stack enumeration and conversion.
To satisfy exact total/running counts, use a separately configured read-only Docker metrics endpoint, or add an upstream Dockge event exposing those counts. Do not enable Dockge’s interactive console just to run arbitrary Docker commands for a widget.
Socket.IO authentication sequence
- Connect to the Dockge origin using Socket.IO client 4 (default
/socket.iopath). Register event/error listeners before authenticating; use explicit connection/ack deadlines and disconnect in a finally block. - Emit
loginByToken, token string, ack. Ack success is{ok:true}; failures include{ok:false,msg:"authInvalidToken",msgi18n:true}. Token is the existing Dockge JWT; password changes invalidate it. - Alternatively emit
login,{username,password}, ack. Success{ok:true,token:"JWT"}; invalid credentials{ok:false,msg:"authIncorrectCreds"}. Accounts with 2FA return{tokenRequired:true}when no TOTP is supplied. A permanently configured one-time TOTP cannot support periodic polling, so prefer JWT for an integration with an existing 2FA account. - Authentication triggers
afterLogin, which asynchronously sends stack lists. Auth data is per connection; HTTP Basic auth/API-key headers are not this authentication protocol.
Login handlers, frontend protocol.
Agent event envelope
To call local read-only events:
socket.emit("agent", "", "dockerStats", ack);
socket.emit("agent", "", "requestStackList", ack);
socket.emit("agent", "", "serviceStatusList", stackName, ack);The empty endpoint selects the directly connected server. A configured agent endpoint selects a remote Docker host. Do not silently combine agents into a local host total. Agent proxy handler.
Server pushes arrive as socket.on("agent", (eventName, payload) => ...), e.g. eventName stackList and payload {ok:true, endpoint:"", stackList:{stackName:{name,status,tags:[],isManagedByDockge,composeFileName,endpoint}}}. requestStackList ack is merely {ok:true,msg:"Updated",msgi18n:true}; the actual list is a separate push. Server emitter/list.
dockerStats ack:
{ ok: true, dockerStats: { containerName: { Name: "containerName", /* docker stats JSON fields */ } } }serviceStatusList ack:
{ ok: true, serviceStatusList: { serviceName: [{ name: "containerName", status: "running" }] } }Health may replace state (healthy, unhealthy, starting), so status does not consistently equal running. Upstream Docker failures are caught and can become an empty stats map, indistinguishable from zero running containers. Document this upstream limitation. Docker handlers, collection methods, stats method.
Avoid getStack for counting
It only adds composeYAML, composeENV, and primaryHostname to the summary. It does not add container instances/counts, and retrieving it exposes potentially secret environment values. Stack serialization.
Selected implementation: Docker Engine GET /info
Configure a distinct Docker API/proxy URL while preserving the Dockge web URL as the item launch destination. GET /info responds with Docker’s SystemInfo JSON, including:
Containers: integer, total number of containers on the host.ContainersRunning: integer, number of containers with status running.- Additional upstream fields such as
ContainersPausedandContainersStoppedneed not be forwarded to the widget.
This is directly defined in the official Engine API v1.45 SystemInfo reference, versioned official OpenAPI source (SystemInfo properties and /info GET), and current Go response type. It yields actual daemon-wide container counts, including containers outside Dockge-managed stacks. It does not require Socket.IO or a Socket.IO dependency.
The integration requires an existing reachable Docker API or restricted read-only proxy endpoint; adding this adapter does not deploy or expose such an endpoint. Do not change network exposure or mount the Docker socket as part of this widget implementation. Validate both fields as nonnegative integers, reject unavailable/malformed responses instead of showing zero, and return only the desired aggregate counts.