Dashboard for Docker Swarm Cluster
Docker-Image Size: < 25 MB
Use a stable release in production, not the master-build! Don't expose this service to the world! The endpoints offer the configuration of your services.
If you like this project, please give a ⭐ on github. Feedback would be nice.
| Tag | Description | Image |
|---|---|---|
| e.g. 1.4.1 | Stable release | ghcr.io/heckenmann/docker-swarm-dashboard:1.4.1 |
| latest | Latest stable release | ghcr.io/heckenmann/docker-swarm-dashboard:latest |
| master | Current unstable master-build (not well tested) | ghcr.io/heckenmann/docker-swarm-dashboard:master |
Docker Swarm Dashboard supports environment variables for configuration.
| Environment variable | Description | Default |
|---|---|---|
DSD_HTTP_PORT |
HTTP port within the container. Usually does not need to be changed. | 8080 |
DSD_HIDE_CONFIG_CONTENT |
Hide config content in detail views, REST detail responses, and MCP get_config. Set to false to display the full content independently of DSD_MASK_ENV. Invalid values keep content hidden. |
true |
DSD_HANDLE_LOGS |
Set to false to prevent fetching and displaying logs. |
true |
DSD_LOG_BUFFER_SIZE |
Maximum number of log lines buffered while streaming to a slow WebSocket client. Must be a positive integer. | 64 |
DSD_MCP_ENABLED |
Enable the built-in Model Context Protocol (MCP) server and MCP connection page. | true |
DSD_DASHBOARD_LAYOUT |
Default dashboard layout. Either row (default) or column. |
row |
DSD_HIDE_SERVICE_STATES |
Comma-separated list of states to not show in the main dashboard. | (none) |
DSD_PATH_PREFIX |
Set a URL path prefix for the dashboard (e.g. /dashboard). Useful when running behind a reverse proxy or when the app should not be served from the root path. |
/ |
DSD_ALLOWED_ORIGINS |
Comma-separated list of allowed HTTP CORS and WebSocket origins (e.g. https://dashboard.example.com). The default keeps the historical behavior and allows all origins. Set a concrete allow-list to restrict browser access. |
* |
DSD_MASK_ENV |
Masks the secrets of the container specs served by the services, tasks and nodes endpoints: environment variable values, labels, credential specs, and the secrets carried by the command line and by the health check. Variable names, flags and the values of the flags that do not look like secret holders stay visible, so --log-level=debug remains readable; a secret is replaced by a fixed-length placeholder. Set to false to expose the raw values. |
true |
DSD_NODE_EXPORTER_LABEL |
Docker service label to identify node-exporter service for metrics collection. | dsd.node-exporter |
DSD_CADVISOR_LABEL |
Docker service label to identify cAdvisor service for container memory metrics. | dsd.cadvisor |
DSD_METRICS_TIMEOUT |
Exporter HTTP request timeout: positive seconds or a Go duration such as 500ms or 10s. Invalid values fall back to the default. |
5s |
DSD_NODE_EXPORTER_PATH / DSD_CADVISOR_PATH |
Exporter metrics path, including an optional query string. | /metrics |
DSD_NODE_EXPORTER_PORT / DSD_CADVISOR_PORT |
Explicit internal exporter port (1–65535), overriding service port discovery. | Auto-detected; fallback 9100 / 8080 |
DSD_NODE_EXPORTER_SCHEME / DSD_CADVISOR_SCHEME |
Exporter URL scheme: http or https. |
http |
DSD_NODE_EXPORTER_HEADERS / DSD_CADVISOR_HEADERS |
JSON object of additional HTTP headers for exporter requests, including optional Host. |
None |
LOCALE |
Timestamp format based on a BCP 47 language tag. | (system) |
TZ |
IANA Time zone to display timestamps in. | (system) |
DSD_VERSION_CHECK_ENABLED |
When true, the system will check for updates and notify in the UI if a new version is available. |
false |
DSD_VERSION_CHECK_CACHE_TIMEOUT_MINUTES |
Cache duration in minutes for version check results. | 60 |
DSD_WELCOME_MESSAGE |
If set, this message will be displayed to the user in a modal dialog when the web application is opened in the browser. | (none) |
DOCKER_API_VERSION |
Forces a specific Docker API version to use (e.g. 1.35, 1.41). When not specified, the server automatically negotiates the highest API version supported by both the client and Docker daemon. Only set this if you need to force a specific version for compatibility. |
(auto-negotiated) |
If DSD_ALLOWED_ORIGINS is not set, the server logs a startup warning because all HTTP CORS and WebSocket origins are allowed for backward compatibility.
These environment variables control the default UI state. All settings can be changed by the user in the web interface and are persisted in the URL hash.
| Environment variable | Description | Default |
|---|---|---|
DSD_TABLE_SIZE |
Default table size. Either sm (small) or lg (large). |
sm |
DSD_SERVICE_NAME_FILTER |
Default service name filter value. | (none) |
DSD_STACK_NAME_FILTER |
Default stack name filter value. | (none) |
DSD_FILTER_TYPE |
Default filter type. Either service or stack. |
service |
DSD_LOGS_NUMBER_OF_LINES |
Default number of log lines to fetch. | 100 |
DSD_LOGS_MESSAGE_MAX_LEN |
Maximum length of log messages to display. | 2000 |
DSD_LOGS_FORM_TAIL |
Default line count or all for the logs form and omitted MCP log tails. |
20 |
DSD_LOGS_FORM_SINCE |
Default value for since option in logs form. | false |
DSD_LOGS_FORM_SINCE_AMOUNT |
Default amount for since option in logs form. | 15 |
DSD_LOGS_FORM_SINCE_UNIT |
Default unit for since option in logs form. Either minutes, hours, or days. |
minutes |
DSD_LOGS_FORM_FOLLOW |
Default value for follow option in logs form. | false |
DSD_LOGS_FORM_TIMESTAMPS |
Default value for timestamps option in logs form. | true |
DSD_LOGS_FORM_STDOUT |
Default value for stdout option in logs form. | true |
DSD_LOGS_FORM_STDERR |
Default value for stderr option in logs form. | true |
DSD_LOGS_FORM_DETAILS |
Default value for details option in logs form. | true |
DSD_LOGS_SEARCH_KEYWORD |
Default search keyword for logs. | (none) |
DSD_DARK_MODE |
Enable dark mode by default. Either true or false. |
false |
DSD_SHOW_NAMES_BUTTONS |
Show action buttons in entity names by default. Either true or false. |
true |
DSD_SHOW_NAV_LABELS |
Show navigation labels by default. Either true or false. |
false |
DSD_MAX_CONTENT_WIDTH |
Maximum content width. Either fluid (full width) or fixed (container width). |
fluid |
The Networks page lists Docker networks and missing network IDs referenced by
service specifications. Details show IPAM subnets/gateways, options,
encryption configuration, aliases, endpoint mode, VIPs, and published ports.
Network details present all sections together in a responsive dashboard without
tabs: metadata, services, IPAM, options, labels, local endpoints, peers, and raw JSON.
Service, stack, and port links open the corresponding dashboard views. Service
details link back to networks. Network details use the shareable networksDetail
URL-hash view with the full Docker network ID.
GET /docker/networks accepts name, stack, driver, and scope filters.
GET /docker/networks/{id} inspects one network on demand. Equivalent read-only
MCP tools are list_networks (same filters) and get_network (identifier: full
network ID). Both interfaces share their queries and metadata masking policy.
List refreshes use one NetworkList and one ServiceList, without per-network
inspection. Docker failures produce errors rather than an empty inventory.
Attachments are joined by network ID, including observed VIP references such as ingress. Missing references and networks deleted between list and inspect are marked explicitly. Endpoints and peers belong to the queried Docker daemon; remote overlay endpoints may be absent. Missing optional data is not evidence of connectivity. Configuration and service attachments do not prove end-to-end reachability. See Docker Swarm networking and the overlay driver.
The Configs and Secrets pages provide separate read-only inventories and
metadata details. Details list every consuming service
and its declared file target, UID, GID, and octal mode; runtime config targets are
identified separately. Service and stack links lead back to the existing views. The service detail
page shows tasks, configs, and secrets together in the first Resources tab.
Config and secret names use the standard detail action to open their dedicated
detail pages directly by ID. Inventories and
detail pages have separate URL-hash views (configs / configsDetail and
secrets / secretsDetail); details can be linked directly and refreshed.
REST endpoints are GET /docker/configs, GET /docker/secrets, and their
/{id} detail routes (under DSD_PATH_PREFIX when configured). List queries
accept name (case-insensitive substring), stack (exact name), and usage
(referenced, unreferenced, or unknown). Equivalent MCP tools are
list_configs, list_secrets, get_config, and get_secret; detail tools take
identifier as the resource ID.
Responses include IDs, names, Docker version indexes, creation/update timestamps,
stack labels, masked metadata labels, and service mount references. List responses
always exclude payloads. Config details show a content visibility status: content
is hidden by default (DSD_HIDE_CONFIG_CONTENT=true). Set this variable to false
to retrieve and display the full config content through the detail page, REST
GET /docker/configs/{id}, and MCP get_config. Text is returned as UTF-8;
binary content is represented as Base64. Empty configs are distinguished from
unavailable content. Secret payloads are never returned.
DSD_MASK_ENV continues to control metadata masking independently; it has no
effect on config content visibility. Names and timestamps do not imply
an expiry date, rotation schedule, or version-name convention.
Usage is recomputed from current service specifications on every refresh. If the
service query fails, usageKnown=false and resources have usage=unknown; they
are never classified as unused. Missing resource IDs still referenced by services
are included with missing=true, accounting for changes between Docker queries.
These queries are not an atomic cluster snapshot. Unreferenced resources are
shown as cleanup candidates for operator review; the dashboard never deletes them.
The Nodes page groups control-plane status and cluster-wide resources in a shared Cluster Overview. It shows manager reachability, the reported leader, the majority required for quorum, and an estimated reserve for additional manager failures. Warnings identify single or even manager sets, unreachable or unknown managers, and missing leaders or insufficient observed reachable managers. Warning links open the affected nodes. The inventory includes each node's advertised Docker Engine version, OS, architecture, and scheduling availability.
This uses Docker node information and works without node-exporter. Reachability is separate from scheduling availability: a drained manager may still participate in consensus. Docker-reported observations are not an independent Raft probe; existing workloads may continue while cluster administration is unavailable.
GET /docker/cluster/health and MCP get_cluster_health share the same read-only
assessment. Responses include available, state, observedAt (UTC), manager
counts, majority, remainingFailures, leaderIds, structured warnings, and a
node inventory. Unknown reachability or a missing/ambiguous leader makes the
reserve unknown (null). Counts refer to managers configured in the returned
node list, not an independently verified Raft membership list.
Docker node queries for this assessment have a five-second deadline. On failure,
REST returns HTTP 503 and MCP returns available: false, state: "unavailable",
with no successful observation timestamp or reserve. Old successful observations
are never substituted for failed queries. Refresh uses the dashboard's existing
refresh controls.
The existing /health endpoint retains its Docker connectivity check.
Docker Swarm Dashboard includes a built-in, read-only MCP server so
MCP-capable agents can inspect the same cluster information that is available
through the web UI. MCP is enabled by default and can be disabled with
DSD_MCP_ENABLED=false.
The server uses Streamable HTTP. Its endpoint is /mcp and follows
DSD_PATH_PREFIX:
https://dashboard.example.com/mcp
https://dashboard.example.com/docker-dashboard/mcp
When MCP is enabled, the dashboard shows an MCP navigation entry. The MCP page displays the endpoint for the current deployment and provides generic connection instructions for MCP-capable agents.
To connect an agent:
- Open the MCP/server configuration in the agent or client.
- Add a remote MCP server.
- Select Streamable HTTP.
- Use
docker-swarm-dashboardas the server name. - Paste the MCP URL displayed by the dashboard.
- Connect and let the client discover the available tools.
The MCP server exposes read-only information for services, nodes, tasks,
metrics, logs (when DSD_HANDLE_LOGS=true), stacks, published ports, the
timeline, dashboard settings, version, and health. Existing
DSD_MASK_ENV masking is also applied to data returned through MCP.
Tools include list_services, get_service, get_service_metrics,
list_nodes, get_node, get_node_metrics, get_cluster_metrics, get_cluster_health,
list_tasks, get_task, get_task_metrics, list_stacks,
list_networks, get_network, list_published_ports, get_timeline, get_cluster_overview,
get_dashboard_settings, get_version, and get_health. When logs are
enabled, list_log_services and get_service_logs are also discoverable.
Service queries accept IDs or exact names, node queries accept IDs, node
names or hostnames, and task queries accept IDs. list_tasks accepts optional
service and node filters.
Results contain structured JSON objects, with named fields such as services,
nodes, tasks, stacks, ports, and timeline for lists, plus a text
fallback for clients using older MCP protocol versions. The cluster overview
contains services, nodes and tasks independently of the dashboard layout.
Log queries return finite snapshots, support the dashboard's Docker log
options, and stop with an error if Docker does not finish within five seconds.
An omitted tail uses logsFormTail from dashboard settings, falling back to
20; an omitted since applies no time filter. Boolean log options use the
configured dashboard defaults. Tool discovery describes these defaults.
Metrics results expose availability and diagnostic messages when exporters are
missing or fail. Check available, message, and error before using metric
values, including when available is true. Exporter HTTP requests have a
five-second timeout, and Docker/exporter work honors request cancellation.
The connection URL uses the server's configured path prefix and the current
browser origin; a client-side API URL override does not change it.
The WebSocket log viewer decodes Docker multiplex frames before splitting text
into lines and preserves raw output for TTY services. Non-follow requests wait
for a complete snapshot instead of treating a pause in output as completion.
A snapshot that does not finish within 20 seconds, or contains an incomplete
Docker frame, closes with an error. MCP log requests use the five-second limit
described above. For the WebSocket viewer, omitted tail or tail=all
returns all available history, tail=0 returns no historical lines, and a
positive number selects the last N lines. Invalid values fall back to 20,
consistently for the Docker request and the returned snapshot.
For finite snapshots, Docker Swarm returns at most the requested number of
lines from each task's log history. The dashboard orders these candidates by
Docker timestamps and then applies the requested tail across the service. This
keeps normal tail requests bounded to the requested count per task instead of
reading each task's full history. The returned lines are oldest-to-newest, and
valid timestamps are fetched internally even when their display is disabled.
Lines with missing or malformed timestamps are retained in their original
order before timestamped lines. Equal timestamps retain Docker's arrival order.
This ordering uses timestamps supplied by each node, so clock skew can affect
the apparent chronology. An explicit tail=all still reads all available
history.
Follow mode keeps Docker's arrival order and does not wait for delayed task logs. Its reader uses a bounded queue, avoiding unbounded buffering at the cost of not reordering late entries in a live stream.
docker pull ghcr.io/heckenmann/docker-swarm-dashboard:master
---
version: '3.5'
services:
docker-swarm-dashboard:
image: ghcr.io/heckenmann/docker-swarm-dashboard:master
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
ports:
- "8080:8080"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
environment:
DSD_MCP_ENABLED: 'true'
This configuration sets a password for access. It is importand to configure ssl in traefik for better security.
In this example you can login with "docker / docker" on port 8080.
Have a look at https://doc.traefik.io/traefik/user-guides/docker-compose/acme-tls/
---
version: '3.5'
services:
docker-swarm-dashboard:
image: ghcr.io/heckenmann/docker-swarm-dashboard:master
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
labels:
- "traefik.enable=true"
- "traefik.http.routers.dsd.entrypoints=web"
- "traefik.http.routers.dsd.middlewares=basic-auth"
- "traefik.http.services.dsd.loadbalancer.server.port=8080"
- "traefik.http.routers.dsd.rule=PathPrefix(`/`)"
# Login with docker / docker
- "traefik.http.middlewares.basic-auth.basicauth.users=docker:$$2y$$10$$81nFbUw842iBd7MlngMR4.1VBI9j6Y.vTiamBAqtVNfs4qehzZB.e"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
traefik:
image: "traefik:v2.9"
deploy:
placement:
constraints:
- node.role == manager
command:
#- "--log.level=debug"
#- "--api.insecure=true"
- "--providers.docker=true"
- "--providers.docker.swarmMode=true"
- "--providers.docker.exposedbydefault=false"
- "--entrypoints.web.address=:8080"
ports:
- "8080:8080"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:ro"
From the directory with docker-compose.yml run:
docker stack deploy --compose-file docker-compose.yml docker-swarm-dashboard
Docker Swarm Dashboard supports optional integration with Prometheus Node Exporter and cAdvisor for enhanced metrics visualization.
| Metric Source | Provides | Discovery Label | Default Label |
|---|---|---|---|
| Node Exporter | Node-level metrics (CPU, memory, disk, network) | dsd.node-exporter |
dsd.node-exporter=true |
| cAdvisor | Container-level metrics (memory usage per container) | dsd.cadvisor |
dsd.cadvisor=true |
Both services should be deployed as global services on the same overlay network as the dashboard.
Exporter endpoint settings use this priority: service labels, dashboard environment
variables, then the existing discovery defaults. Set labels under deploy.labels
on the exporter service, for example:
deploy:
labels:
dsd.node-exporter: "true"
dsd.node-exporter.path: "/prometheus/metrics"
dsd.node-exporter.port: "19100"
dsd.node-exporter.scheme: "https"For cAdvisor, use dsd.cadvisor.path, dsd.cadvisor.port, and
dsd.cadvisor.scheme. These configuration labels remain fixed even if the
discovery label is customized. Ports refer to the exporter listener reachable
inside the overlay network. Discovery still selects the task on the requested
node and prefers a network shared with the dashboard.
Paths must start with a single /; fragments and absolute URLs are rejected.
Invalid endpoint settings make the affected metrics unavailable with a diagnostic
error. HTTPS uses the system certificate trust store. Reverse proxies can receive
custom headers through the dashboard environment, for example
DSD_NODE_EXPORTER_HEADERS='{"Host":"metrics.internal","X-Tenant":"operations"}'.
Malformed header JSON fails the request without logging its contents. Keep
credentials out of service labels.
DSD_METRICS_TIMEOUT is read when the dashboard starts and limits each exporter
HTTP request, including its response body. Earlier request cancellation still
takes precedence. These settings apply to node, cluster, service, and task metrics
in both the dashboard and MCP tools.
Purpose: Displays node-level system metrics (CPU, memory, disk, network usage per swarm node).
Deployment:
node-exporter:
image: prom/node-exporter:latest
deploy:
mode: global
placement:
constraints:
- node.role == manager # Or remove for all nodes
labels:
- "dsd.node-exporter=true"
networks:
- your-network-name
volumes:
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- /:/rootfs:ro
command:
- '--path.procfs=/host/proc'
- '--path.sysfs=/host/sys'
- '--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)'Customize Discovery Label:
environment:
DSD_NODE_EXPORTER_LABEL: "my.custom.label"Purpose: Displays container-level memory metrics per service (memory usage, limits, per-container breakdown).
Deployment:
cadvisor:
image: gcr.io/cadvisor/cadvisor:latest
deploy:
mode: global
placement:
constraints:
- node.role == manager # Or remove for all nodes
labels:
- "dsd.cadvisor=true"
networks:
- your-network-name
volumes:
- /:/rootfs:ro
- /var/run:/var/run:ro
- /sys:/sys:ro
- /var/lib/docker/:/var/lib/docker:ro
- /dev/disk/:/dev/disk:ro
command:
- '--docker_only=true'
- '--housekeeping_interval=30s'Customize Discovery Label:
environment:
DSD_CADVISOR_LABEL: "my.custom.label"Node Exporter Metrics:
- CPU usage per node
- Memory usage per node
- Disk I/O and storage
- Network traffic per node
cAdvisor Metrics (Service Metrics Tab):
- Total Memory Usage: Aggregate memory usage across all containers in the service
- Memory Limits: Configured memory limits for each container
- Per-Container Breakdown: Memory usage for each task/container in the service
- Usage Percentage: Memory usage as a percentage of the configured limit
Benefits of cAdvisor:
- Identify memory-hungry containers within a service
- Monitor services approaching memory limits
- Detect potential out-of-memory (OOM) situations before they occur
Both services should be attached to the same overlay network as the dashboard for container-to-container communication:
networks:
- your-network-name # Same network as docker-swarm-dashboardThis ensures metrics are only reachable from within the overlay network (recommended for security).
docker service create --name logger chentex/random-logger:latest 50 200
Read the UI guidelines before changing frontend tables, icons, filters, or entity actions.
docker build -t ghcr.io/heckenmann/docker-swarm-dashboard:local .
# from app-src
yarn run start-api-mock
# from app-src
yarn run start-dev-server
When you run the UI with the api-mock-server, you have to open the ui with "base"-param (API-URL): http://localhost:3000#base="http%3A%2F%2Flocalhost%3A3001%2F"
# from app-src
yarn run cy:run







