{"id":13583692,"url":"https://github.com/bobf/skep","last_synced_at":"2025-04-06T21:32:51.610Z","repository":{"id":35504645,"uuid":"185072030","full_name":"bobf/skep","owner":"bobf","description":"Docker Swarm web and console dashboard","archived":false,"fork":false,"pushed_at":"2023-01-07T04:10:09.000Z","size":5036,"stargazers_count":29,"open_issues_count":41,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-02T15:53:46.751Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bobf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-05T19:12:55.000Z","updated_at":"2023-09-27T19:12:07.000Z","dependencies_parsed_at":"2023-01-15T22:21:45.978Z","dependency_job_id":null,"html_url":"https://github.com/bobf/skep","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobf%2Fskep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobf%2Fskep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobf%2Fskep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bobf%2Fskep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bobf","download_url":"https://codeload.github.com/bobf/skep/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223264902,"owners_count":17116235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:03:42.206Z","updated_at":"2024-11-06T00:30:37.337Z","avatar_url":"https://github.com/bobf.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"## Overview\n\n_Skep_ is a monitoring dashboard for [_Docker Swarm_](https://docs.docker.com/engine/swarm/).\n\n![Skep](doc/images/screenshot.png)\n\nSee [skepdocker.github.io](https://skepdocker.github.io/) for more screenshots, features, etc..\n\nYou may find _Skep_ to be a useful addition to your toolbox along with projects like these:\n\n* [Swarmpit](https://swarmpit.io/)\n* [SwarmProm](https://github.com/stefanprodan/swarmprom)\n* [swarm-dashboard](https://github.com/charypar/swarm-dashboard)\n* [docker-swarm-visualizer](https://github.com/dockersamples/docker-swarm-visualizer)\n* [portainer.io](https://www.portainer.io/)\n* [Consul](https://www.consul.io/)\n\n## Configuration/Setup\n\n### Quickstart\n\nLaunch _Skep_ using the default configuration by running the following command on any _Swarm_ manager:\n```\ncurl -sSL https://raw.githubusercontent.com/bobf/skep/master/docker-compose.yml | docker-compose -f - config | docker stack deploy -c - skep\n```\n\n_Skep_ will be available on any _Swarm_ node on port `8080`.\n\nWhen you have finished evaluating _Skep_ you can remove the stack to destroy all services and networks:\n```\ndocker stack rm skep\n```\n\n### Configuration\n\nThe _agent_ service is responsible for harvesting host and container metrics; configure this service as appropriate for your hardware/operating system setup.\n\nSee the sections below to configure each of _Skep_'s components. The provided [example docker-compose.yml](docker-compose.yml) can be used as a starting point.\n\nWhen you have a `docker-compose.yml` that suits your requirements you can launch _Skep_ by executing the following command on any _Swarm_ manager:\n\n```\ndocker-compose -f \u003cyour-compose-file.yml\u003e config | docker stack deploy -c - skep\n```\n\n#### Front end web app\n\n| Variable | Meaning | Example |\n|-|-|-|\n| `SKEP_PRIVATE_PORT` | Port used for internal communications between _Skep_ services. Do not publish this port. | `6666` _(default/recommended)_ |\n\n#### Agent\n\n| Variable | Meaning | Example |\n|-|-|-|\n| `SKEP_APP_URL` | URL that agent containers will use to send metrics to _Skep_ web application | `http://app:6666/` _(default/recommended)_ |\n| `DISKS` | Comma-separated list of disk devices to monitor (disk activity) | `sda,sdc` |\n| `FILE_SYSTEMS` | Comma-separated list of file systems to monitor (available space) | `/hostfs/root,/hostfs/backups` (see [file systems](#file-systems)) |\n| `NETWORK_INTERFACES` | Comma-separated list of network devices to monitor (traffic) **[not yet implemented]** | `eth0,eth3` |\n| `COLLECT_INTERVAL` | Time in seconds to wait between gathering metrics. | `5` |\n| `SAMPLE_DURATION` | _Minimum_ time in seconds to monitor disk I/O etc. Will accumulate for multiple devices. | `10` |\n| `LOG_LEVEL` | By default, the agent only logs initial configuration on launch and errors. Set to `DEBUG` to log all statistics. | `INFO` _(default/recommended)_ |\n| `SKEP_HOST` | Set to `docker-desktop` when running on Docker Desktop for Mac | `docker-desktop` |\n\n#### Monitor\n\n| Variable | Meaning | Example |\n|-|-|-|\n| `SKEP_APP_URL` | URL that agent containers will use to send metrics to _Skep_ web application | `http://app:6666/` _(default/recommended)_ |\n| `SERVICE_URL_TEMPLATE` | URL template for service names | See [URL templating](#url-templating) |\n| `IMAGE_URL_TEMPLATE` | URL template for image names | See [URL templating](#url-templating) |\n| `LOG_LEVEL` | By default, the monitor only logs initial configuration on launch and errors. Set to `DEBUG` to log all statistics. | `INFO` _(default/recommended)_ |\n| `COLLECT_INTERVAL` | Time in seconds to wait between gathering metrics. | `5` |\n| `SAMPLE_DURATION` | _Minimum_ time in seconds to monitor disk I/O etc. Will accumulate for multiple devices. | `10` |\n\n#### Monitor\n\n| Variable | Meaning | Example |\n|-|-|-|\n| `SKEP_APP_URL` | URL that agent containers will use to send metrics to _Skep_ web application | `http://app:6666/` _(default/recommended)_ |\n| `SERVICE_URL_TEMPLATE` | URL template for service names | See [URL templating](#url-templating) |\n| `IMAGE_URL_TEMPLATE` | URL template for image names | See [URL templating](#url-templating) |\n| `LOG_LEVEL` | By default, the monitor only logs initial configuration on launch and errors. Set to `DEBUG` to log all statistics. | `INFO` _(default/recommended)_ |\n| `COLLECT_INTERVAL` | Time in seconds to wait between gathering metrics. | `5` |\n| `SAMPLE_DURATION` | _Minimum_ time in seconds to _monitor_ disk I/O etc. Will accumulate for multiple devices. | `10` |\n\n#### Charts\n\n| Variable | Meaning | Example |\n|-|-|-|\n| `SKEP_APP_URL` | URL that agent containers will use to send metrics to _Skep_ web application | `http://app:6666/` _(default/recommended)_ |\n| `SKEP_CHARTS_URL` | URL that the _charts_ service will be available on for handling chart requests. Sent to _App_ service every time charts are updated. | `http://charts:8080/`\n| `SKEP_CHARTS_DB_PATH` | Path to statistics _SQLite3_ database. Mount a shared storage endpoint to this location if you want to retain data between restarts. | `/charts.db` _(default/recommended)_ |\n| `SKEP_CHARTS_DB_PERSIST` | By default, the statistics database is re-initialised on startup. Set this variable to any value to retain data between restarts. | _(not set)_ |\n| `LOG_LEVEL` | Application server log level. | `INFO` _(default/recommended)_ |\n\n## Deployment\n\n_Skep_ uses the [gunicorn](https://gunicorn.org/) web server in conjunction with [Flask](https://palletsprojects.com/p/flask/) and [Flask-SocketIO](https://github.com/miguelgrinberg/Flask-SocketIO).\n\nTo deploy _Skep_ behind _Nginx_ the following configuration can be used:\n```\nupstream skep {\n  # Docker Swarm Nodes:\n  server node1:8080;\n  server node2:8080;\n  server node3:8080;\n}\n\nserver {\n    server_name skep.example.com;\n\n    location / {\n        proxy_pass http://skep;\n    }\n\n    location /socket.io {\n        proxy_http_version 1.1;\n        proxy_buffering off;\n        proxy_set_header Origin \"\";\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"Upgrade\";\n        proxy_pass http://skep;\n    }\n\n    listen 80;\n    listen [::]:80;\n}\n```\n\n\u003ca name=\"file-systems\"\u003e\u003c/a\u003e\n## File Systems\n\nTo monitor a file system it must be mounted into the agent as a [_Docker_ bind mount](https://docs.docker.com/storage/bind-mounts/). The `FILE_SYSTEMS` environment variable should refer to the **destination** of the bind mount. _Skep_ uses the base path `/hostfs` for mounting host file systems but any valid path is acceptable.\n\nFor example, to monitor the root file system, the following configuration might be used:\n\n```yaml\n  stats:\n    image: skep/stats\n\n    volumes:\n      - \"/:/hostfs/root:ro\"\n\n    environment:\n      FILE_SYSTEMS: '/hostfs/root'\n```\n\n\u003ca name=\"url-templating\"\u003e\u003c/a\u003e\n## URL Templating\n\nURL templating is supported for service names and image IDs. When the relevant environment variable is set, service names and image IDs will be rendered as hyperlinks according to a provided _Python_ format string. See the table below for available parameters:\n\n### Service Name\n\n| Parameter | Meaning | Example |\n|-|-|-|\n| `name` | Name of service | `skep_app` |\n| `id` | Service ID | `yw1iaod282a7` |\n\n### Image\n\n| Parameter | Meaning | Example |\n|-|-|-|\n| `organization` | Image organization owner | `skep` |\n| `repository` | Image repository name | `app` |\n| `tag` | Image tag | `latest` |\n\n### Example\n\n```\n# .env\nSERVICE_URL_TEMPLATE=https://github.com/bobf/{name}\nIMAGE_URL_TEMPLATE=https://hub.docker.com/r/{organization}/{repository}\n```\n\n## Architecture\n\n_Skep_ is comprised of four services:\n\n* An _agent_ which is deployed globally (i.e. to all _Swarm_ nodes);\n* A _monitor_ which must be deployed to one manager node;\n* A _charts_ service which stores and calculates chart data which can be deployed to any node and must have only one replica;\n* A web _app_ that can be deployed to any node and must have only one replica.\n\nThe _agent_ periodically harvests system and container metrics which are sent to the _charts_ and _app_ services; the _app_ service forwards the data to the [_React_](https://reactjs.org/) front end using [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) / [socket.io](https://socket.io/). The _charts_ service retains the data in an [SQLite3](https://www.sqlite.org/version3.html) database.\n\nChart requests are sent to the _app_ which forwards to the _charts_ service. A confirmation is immediately returned to the front end while the _charts_ service uses one of its worker processes to render the chart data. When the data has been compiled it is sent back to the front end via a _WebSocket_ event.\n\n_Redux_ is used in the front end to manage events and data storage/manipulation.\n\n_Agents_ use bind mounts to access metrics from the host system (`/proc`, `/etc/`, and `/dev` are mounted). _Agents_ also gather statistics about containers running on each host by mounting the _Docker_ socket (`/var/run/docker.sock`).\n\nAll services are written in _Python 3_.\n\n_Skep_ utilises the excellent [Docker SDK for Python](https://docker-py.readthedocs.io/en/stable/index.html) extensively.\n\nThe web application uses the equally excellent [Flask](http://flask.pocoo.org/) web framework and [Flask-SocketIO](https://flask-socketio.readthedocs.io/en/latest/).\n\nThe front end is read-only. No changes to a swarm can be made via the web application. A best-effort approach to filter sensitive data (e.g. passwords in environment configurations) is implemented using simple heuristics. Regardless, as with all similar systems, it is highly recommended that you run _Skep_ behind a firewall and/or an authentication layer.\n\n## License\n\n[MIT License](LICENSE)\n\n## Contributing\n\nFeel free to make a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobf%2Fskep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbobf%2Fskep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbobf%2Fskep/lists"}