Skip to content

Commit

Permalink
Update readme: add list of environment variables
Browse files Browse the repository at this point in the history
  • Loading branch information
@mohsenasm
mohsenasm committed Oct 21, 2023
1 parent e24b3de commit d3bde78
Show file tree
Hide file tree
Showing 5 changed files with 82 additions and 41 deletions.
108 changes: 69 additions & 39 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,68 +4,95 @@ A simple monitoring dashboard for Docker in Swarm Mode.

![Example Dashboard](./swarm.gif)

## About
Swarm Dashboard shows you all the tasks running on a Docker Swarm organized
by service and node. It provides a space-efficient visualization
and works well at a glance. You can use it as a simple live dashboard of the state of your Swarm.

Swarm dashboard shows you all the tasks running on a Docker Swarm organized
by service and node. It provides a visualization that's space-efficient
and works well at a glance.
It also shows the CPU/Memory/Disk usage of your swarm node and containers.

You can use it as a simple live dashboard of the state of your Swarm.
## Usage

The Dashboard has a node.js server which streams swarm updates to an Elm client
over a WebSocket.

### Prior art

* Heavily inspired by [Docker Swarm Visualiser](https://github.com/dockersamples/docker-swarm-visualizer)

## Running

At the moment, the dashboard needs to be deployed on one of the swarm managers.
The dashboard needs to be deployed on one of the swarm managers.
You can configure it with the following Docker compose file:

```yml
# compose.yml
version: "3"

services:
dashboard:
image: mohsenasm/swarm-dashboard
swarm-dashboard:
image: mohsenasm/swarm-dashboard:dev_stats
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
- lego-files:/lego-files
- /var/run/docker.sock:/var/run/docker.sock
ports:
- 8081:8081
- 8080:8080
environment:
PORT: 8081
PORT: 8080
ENABLE_AUTHENTICATION: "false"
# ENABLE_AUTHENTICATION: "true"
# AUTHENTICATION_REALM: "KuW2i9GdLIkql"
# USERNAME: "admin"
# PASSWORD: "supersecret"
ENABLE_HTTPS: "false"
# ENABLE_HTTPS: "true"
# HTTPS_HOSTNAME: "example.com"
# LEGO_NEW_COMMAND_ARGS: "--accept-tos [email protected] --domains=example.com --dns cloudflare run"
# LEGO_RENEW_COMMAND_ARGS: "--accept-tos [email protected] --domains=example.com --dns cloudflare renew"
# CLOUDFLARE_EMAIL: "[email protected]"
# CLOUDFLARE_API_KEY: "yourprivatecloudflareapikey"
NODE_EXPORTER_SERVICE_NAME_REGEX: "node-exporter"
CADVISOR_SERVICE_NAME_REGEX: "cadvisor"
deploy:
replicas: 1
placement:
constraints:
- node.role == manager

node-exporter:
image: quay.io/prometheus/node-exporter:v1.6.1
volumes:
- '/:/host:ro'
command:
- '--path.rootfs=/host'
deploy:
mode: global

volumes:
lego-files:
cadvisor:
image: gcr.io/cadvisor/cadvisor
volumes:
- /:/rootfs:ro
- /var/run:/var/run:rw
- /sys:/sys:ro
- /var/lib/docker/:/var/lib/docker:ro
- /dev/disk/:/dev/disk:ro
deploy:
mode: global
```
and deploy with
```
$ docker stack deploy -c compose.yml svc
$ docker stack deploy -c compose.yml sd
```

Note that the usage of `node-exporter` and `cadvisor` are optional, to fetch node CPU/Memory/Disk usage and containers' CPU/Memory usage respectively. If you don't need this feature, make sure to remove `NODE_EXPORTER_SERVICE_NAME_REGEX` and `CADVISOR_SERVICE_NAME_REGEX` envs.

## Advance Usage

List of environment variables for more customization:

| Enviroment Varibles | Example | Considration |
|--------------------------------------|-------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| PORT | 8080 | HTTP / HTTPS port |
| ENABLE_AUTHENTICATION | true | false by default |
| AUTHENTICATION_REALM | MyRealm | Use this env if ENABLE_AUTHENTICATION is `true`. |
| USERNAME | admin | Use this env if ENABLE_AUTHENTICATION is `true`. |
| PASSWORD | supersecret | Use this env if ENABLE_AUTHENTICATION is `true`. |
| ENABLE_HTTPS | true | false by default |
| LEGO_PATH | | Use this env if ENABLE_HTTPS is `true`. Lego is used to create the SSL certificates. Create a named volume for this path to avoid the creation of a new certificate on each run. |
| HTTPS_HOSTNAME | swarm-dashboard.example.com | Use this env if ENABLE_HTTPS is `true`. |
| LEGO_NEW_COMMAND_ARGS | --accept-tos --email=[email protected] --domains=swarm-dashboard.example.com --dns cloudflare run | Use this env if ENABLE_HTTPS is `true`. |
| LEGO_RENEW_COMMAND_ARGS | --accept-tos --email=[email protected] --domains=swarm-dashboard.example.com --dns cloudflare renew | Use this env if ENABLE_HTTPS is `true`. |
| CLOUDFLARE_EMAIL | [email protected] | You can use any DNS provider that Lego supports. |
| CLOUDFLARE_API_KEY | yourprivatecloudflareapikey | You can use any DNS provider that Lego supports. |
| DOCKER_UPDATE_INTERVAL | 1000 | Refresh interval in ms. |
| METRICS_UPDATE_INTERVAL | 5000 | Refresh interval in ms. |
| NODE_EXPORTER_SERVICE_NAME_REGEX | node-exporter | Use this env to enable `node-exporter` integration. |
| NODE_EXPORTER_INTERESTED_MOUNT_POINT | | You may need this config if you have not specified `--path.rootfs=/host` for `node-exporter`. |
| NODE_EXPORTER_PORT | 9100 | |
| CADVISOR_SERVICE_NAME_REGEX | cadvisor | Use this env to enable `cadvisor` integration. |
| CADVISOR_PORT | 8080 | |


## Security

+ We redact docker event data before sending them to the client. The previous version was sending the whole docker event data, including environment variables (someone might have stored some passwords in them, by mistake!). So, please consider using the newer version.
Expand Down Expand Up @@ -93,12 +120,15 @@ There are two considerations for any serious deployment of the dashboard:

* Show more service details (published port, image name, and version)
* Node / Service / Task details panel
* Show node / task resources (CPU & Memory)
* Improve security for potential production use

Both feature requests and pull requests are welcome
Both feature requests and pull requests are welcome.

### Prior art

* Heavily inspired by [Docker Swarm Visualiser](https://github.com/dockersamples/docker-swarm-visualizer)

## Contributors

* Viktor Charypar (owner, BDFL) - code, docs
* Mohammad-Mohsen Aseman-Manzar (current maintainer) - code, docs
* Viktor Charypar (previous repo owner) - code, docs
* Clementine Brown - design
2 changes: 1 addition & 1 deletion server/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ const enableAuthentication = process.env.ENABLE_AUTHENTICATION === "true"
const username = process.env.USERNAME || "admin";
const password = process.env.PASSWORD || "supersecret";
const enableHTTPS = process.env.ENABLE_HTTPS === "true";
const legoPath = process.env.LEGO_PATH;
const legoPath = process.env.LEGO_PATH || "/lego-files";
const httpsHostname = process.env.HTTPS_HOSTNAME;
const dockerUpdateInterval = parseInt(process.env.DOCKER_UPDATE_INTERVAL || "1000");
const metricsUpdateInterval = parseInt(process.env.METRICS_UPDATE_INTERVAL|| "5000");
Expand Down
Binary file modified swarm.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions test-cluster/compose-all.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ services:
ENABLE_AUTHENTICATION: "false"
ENABLE_HTTPS: "false"
NODE_EXPORTER_SERVICE_NAME_REGEX: "node-exporter"
CADVISOR_SERVICE_NAME_REGEX: "cadvisor"
deploy:
placement:
constraints:
Expand All @@ -25,3 +26,14 @@ services:
- '--path.rootfs=/host'
deploy:
mode: global

cadvisor:
image: gcr.io/cadvisor/cadvisor
volumes:
- /:/rootfs:ro
- /var/run:/var/run:rw
- /sys:/sys:ro
- /var/lib/docker/:/var/lib/docker:ro
- /dev/disk/:/dev/disk:ro
deploy:
mode: global
1 change: 0 additions & 1 deletion test-cluster/compose-dashboard.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ services:
networks:
- monitoring_net


networks:
monitoring_net:
external:
Expand Down

0 comments on commit d3bde78

Please sign in to comment.