{"id":14994526,"url":"https://github.com/skx/puppet-summary","last_synced_at":"2025-10-30T04:31:22.387Z","repository":{"id":48042564,"uuid":"99040184","full_name":"skx/puppet-summary","owner":"skx","description":"The Puppet Summary is a web interface providing reporting features for Puppet, it replaces the Puppet Dashboard project","archived":false,"fork":false,"pushed_at":"2024-05-04T05:43:06.000Z","size":2336,"stargazers_count":47,"open_issues_count":4,"forks_count":19,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-02-02T06:31:37.342Z","etag":null,"topics":["golang","puppet","puppet-dashboard","puppet-master","puppet-reports","puppet-server","puppet-summary"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"skx","custom":"https://steve.fi/donate/"}},"created_at":"2017-08-01T20:23:31.000Z","updated_at":"2024-11-07T00:10:20.000Z","dependencies_parsed_at":"2024-05-04T06:29:14.340Z","dependency_job_id":"ea829799-34ff-4de3-a672-3de659f019f6","html_url":"https://github.com/skx/puppet-summary","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fpuppet-summary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fpuppet-summary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fpuppet-summary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skx%2Fpuppet-summary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skx","download_url":"https://codeload.github.com/skx/puppet-summary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238934083,"owners_count":19554788,"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":["golang","puppet","puppet-dashboard","puppet-master","puppet-reports","puppet-server","puppet-summary"],"created_at":"2024-09-24T16:03:46.327Z","updated_at":"2025-10-30T04:31:16.929Z","avatar_url":"https://github.com/skx.png","language":"Go","funding_links":["https://github.com/sponsors/skx","https://steve.fi/donate/"],"categories":["Puppet Tools"],"sub_categories":["Modules Management"],"readme":"[![Go Report Card](https://goreportcard.com/badge/github.com/skx/puppet-summary)](https://goreportcard.com/report/github.com/skx/puppet-summary)\n[![license](https://img.shields.io/github/license/skx/puppet-summary.svg)](https://github.com/skx/puppet-summary/blob/master/LICENSE)\n[![Release](https://img.shields.io/github/release/skx/puppet-summary.svg)](https://github.com/skx/puppet-summary/releases/latest)\n[![gocover store](http://gocover.io/_badge/github.com/skx/puppet-summary)](http://gocover.io/github.com/skx/puppet-summary)\n\nTable of Contents\n=================\n\n* [Puppet Summary](#puppet-summary)\n* [Puppet Reporting](#puppet-reporting)\n* [Installation](#installation)\n  * [Source Installation](#source-installation)\n* [Execution](#execution)\n* [Importing Puppet State](#importing-puppet-state)\n* [Maintenance](#maintenance)\n* [Metrics](#metrics)\n* [Notes On Deployment](#notes-on-deployment)\n  * [Service file for systemd](#service-file-for-systemd)\n* [Github Setup](#github-setup)\n\nPuppet Summary\n==============\n\nThis is a simple [golang](https://golang.org/) based project which is designed to offer a dashboard of your current puppet-infrastructure:\n\n* Listing all known-nodes, and their current state.\n* Viewing the last few runs of a given system.\n* etc.\n\nThis project is directly inspired by the [puppet-dashboard](https://github.com/sodabrew/puppet-dashboard) project, reasons why you might prefer _this_ project:\n\n* It is actively maintained.\n   * Unlike [puppet-dashboard](https://github.com/sodabrew/puppet-dashboard/issues/341).\n* Deployment is significantly simpler.\n   * This project only involves deploying a single binary.\n* It allows you to submit metrics to a carbon-receiver.\n   * The metrics include a distinct count of each state, allowing you to raise alerts when nodes in the failed state are present.\n* The output can be used for scripting, and automation.\n   * All output is available as [JSON/XML](API.md) in addition to human-viewable HTML.\n\nYou can get a good idea of what the project does by looking at the screens:\n\n* [SCREENSHOTS.md](SCREENSHOTS.md)\n\nYou can also consult the API documentation:\n\n* [API.md](API.md)\n\n\n\n## Puppet Reporting\n\nThe puppet-server has integrated support for submitting reports to\na central location, via HTTP POSTs.   This project is designed to be\na target for such submission:\n\n* Your puppet-master submits reports to this software.\n    * The reports are saved locally, as YAML files, beneath `./reports`\n    * They are parsed and a simple SQLite database keeps track of them.\n* The SQLite database is used to present a visualization layer.\n    * Which you can see [in the screenshots](screenshots/).\n\nThe reports are expected to be pruned over time, but as the SQLite database\nonly contains a summary of the available data it will not grow excessively.\n\n\u003e The software has [been reported](https://github.com/skx/puppet-summary/issues/42) to cope with 16k reports per day, archive approximately 27Gb of data over 14 days!\n\n\n\n## Installation\n\nInstalling the service can be done in one of two ways, depending on whether you have the [go](https://golang.org/) toolchain available:\n\n* Download the appropriate binary from our [project release page](https://github.com/skx/puppet-summary/releases).\n* Install from source, as documented below.\n\n\n### Source Installation\n\nIf you're planning to make changes to the code, or examine it, then the obvious approach to installing from source is to clone the code, then build and install it from that local clone:\n\n    git clone https://github.com/skx/puppet-summary\n    cd puppet-summary\n    go install .\n\nYou could install directly from source, without cloning the repository as an interim step, by running:\n\n    go install github.com/skx/puppet-summary@master\n\nIn either case you'll find a binary named `puppet-summary` placed inside a directory named `bin` beneath the golang GOPATH directory.  To see exactly where this is please run:\n\n    echo $(go env GOPATH)/bin\n\n(Typically you'd find binaries deployed to the directory `~/go/bin`, however this might vary.)\n\n\n\n## Execution\n\nOnce installed you can launch it directly like so:\n\n    $ puppet-summary serve\n    Launching the server on http://127.0.0.1:3001\n\nIf you wish to change the host/port you can do so like this:\n\n    $ puppet-summary serve -host 10.10.10.10 -port 4321\n    Launching the server on http://10.10.10.10:4321\n\nTo have it listen on any available IP address, use one of these examples:\n\n    $ puppet-summary serve -host \"\" -port 4321\n    $ puppet-summary serve -host 0.0.0.0 -port 4321\n\nOther sub-commands are described later, or can be viewed via:\n\n    $ puppet-summary help\n\n\n\n## Importing Puppet State\n\nOnce you've got an instance of `puppet-summary` installed and running\nthe next step is to populate it with report data.  The expectation is\nthat you'll update your puppet server to send the reports to it directly,\nby editing `puppet.conf` on your puppet-master:\n\n    [master]\n    reports = store, http\n    reporturl = http://localhost:3001/upload\n\n* If you're running the dashboard on a different host you'll need to use the external IP/hostname here.\n* Once you've changed your master's configuration don't forget to restart the service!\n\nIf you __don't__ wish to change your puppet-server initially you can test\nwhat it would look like by importing the existing YAML reports from your\npuppet-master.  Something like this should do the job:\n\n    # cd /var/lib/puppet/reports\n    # find . -name '*.yaml' -exec \\\n       curl --data-binary @\\{\\} http://localhost:3001/upload \\;\n\n* That assumes that your reports are located beneath `/var/lib/puppet/reports`,\nbut that is a reasonable default.\n* It also assumes you're running the `puppet-summary` instance upon the puppet-master, if you're on a different host remember to change the URI.\n\n\n\n## Maintenance\n\nOver time your reports will start to consuming ever-increasing amounts of disk-space so they should be pruned.  To prune (read: delete) old reports run:\n\n    puppet-summary prune -days 7 -prefix ./reports/\n\nThat will remove the saved YAML files from disk which are over 7 days old, and it will _also_ remove the associated database entries that refer to them.\n\nIf you're happy with the default pruning behaviour, which is particularly useful when you're running this software in a container, described in [HACKING.md](HACKING.md), you can prune old reports automatically once per week without the need to add a cron-job like so:\n\n    puppet-summary serve  -auto-prune [options..]\n\nIf you don't do this you'll need to __add a cronjob__ to ensure that the prune-subcommand runs regularly.\n\nNodes which had previously submitted updates to your puppet-master, and `puppet-summary` service, but which have failed to do so \"recently\", will be listed in the web-based user-interface, in the \"orphaned\" column.  Orphaned nodes will be reaped over time, via the `days` option just discussed.  If you explicitly wish to clean removed-hosts you can do so via:\n\n    puppet-summary prune -verbose -orphaned\n\n\n\n## Metrics\n\nIf you have a carbon-server running locally you can also submit metrics\nto it :\n\n    puppet-summary metrics \\\n      -host carbon.example.com \\\n      -port 2003 \\\n      -prefix puppet.example_com  [-nop]\n\nThe metrics include the count of nodes in each state, `changed`, `unchanged`, `failed`, and `orphaned` and can be used to raise alerts when things fail.  When running with `-nop` the metrics will be dumped to the console instead of submitted.\n\n\n\n## Notes On Deployment\n\nIf you can run this software upon your puppet-master then that's the ideal, that way your puppet-master would be configured to uploaded your reports to `127.0.0.1:3001/upload`, and the dashboard itself may be viewed via a reverse-proxy.\n\nThe appeal of allowing submissions from the loopback is that your reverse-proxy can deny access to the upload end-point, ensuring nobody else can submit details.  A simple nginx configure might look like this:\n\n     server {\n         server_name reports.example.com;\n         listen [::]:80  default ipv6only=off;\n\n         ## Puppet-master is the only host that needs access here\n         ## it is configured to POST to localhost:3001 directly\n         ## so we can disable access here.\n         location /upload {\n            deny all;\n         }\n\n         ## send all traffic to the back-end\n         location / {\n           proxy_pass  http://127.0.0.1:3001;\n           proxy_redirect off;\n           proxy_set_header        X-Forwarded-For $remote_addr;\n         }\n     }\n\n* Please don't run this application as root.\n* The defaults are sane, YAML files are stored beneath `./reports`, and the SQLite database is located at \"`./ps.db`.\n    * Both these values can be changed, but if you change them you'll need to remember to change for all appropriate actions.\n      * For example \"`puppet-summary serve -db-file ./new.db`\",  \"`puppet-summary metrics -db-file ./new.db`\", and \"`puppet-summary prune -db-file ./new.db`\".\n\n\n### Service file for systemd\n\nYou can find instructions on how to create a service file for systemd in the [samples](samples) directory.\n\n\n\n## Github Setup\n\nThis repository is configured to run tests upon every commit, and when\npull-requests are created/updated.  The testing is carried out via\n[.github/run-tests.sh](.github/run-tests.sh) which is used by the\n[github-action-tester](https://github.com/skx/github-action-tester) action.\n\nReleases are automated in a similar fashion via [.github/build](.github/build),\nand the [github-action-publish-binaries](https://github.com/skx/github-action-publish-binaries) action.\n\n\nSteve\n--\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Fpuppet-summary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskx%2Fpuppet-summary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskx%2Fpuppet-summary/lists"}