README.md
1# Puppetboard
2
3[](https://pypi.org/project/puppetboard/)
4[](https://pypi.org/project/puppetboard/)
5/badge.svg)
6[](https://codecov.io/gh/voxpupuli/puppetboard)
7[](http://voxpupuli.org)
8
9
10Puppetboard is a web interface to [PuppetDB](https://puppet.com/docs/puppetdb/latest/index.html) aiming to replace
11the reporting functionality of [Puppet Enterprise console (previously: Puppet Dashboard)](https://puppet.com/docs/pe/latest/console_accessing.html)
12for the open source Puppet.
13
14
15
16See [more screenshots here](#more-screenshots).
17
18## Table of Contents
19
20* [Requirements](#requirements)
21* [Installation](#installation)
22* [Configuration](#configuration)
23* [Getting Help](#getting-help)
24* [Contributing](#contributing)
25* [Legal](#legal)
26
27## Requirements
28
29* PuppetDB v. 3.0-7.5 (will most probably work with newer, but this has not been tested yet)
30* Python 3.6 / 3.7 / 3.8 / 3.9 / 3.10
31
32## Installation
33
34Puppetboard is packaged and available on PyPi.
35
36### With Puppet module
37
38There is a [Puppet module](https://forge.puppetlabs.com/puppet/puppetboard) originally written by
39 [Spencer Krum](https://github.com/nibalizer) and currently maintained by [Voxpupuli](https://voxpupuli.org/)
40that takes care of installing the Puppetboard for you.
41
42To see how to get it working with RedHat/Centos 7 check out these [docs](https://github.com/voxpupuli/puppetboard/blob/master/docs/EL7.md).
43
44### Using Docker
45
46We provide [an official Docker image in the GitHub Container Registry](https://github.com/orgs/voxpupuli/packages/container/package/puppetboard).
47
48You can run the app using it with:
49
50```bash
51docker pull ghcr.io/voxpupuli/puppetboard
52
53docker run -it -p 9080:80 -v /etc/puppetlabs/puppet/ssl:/etc/puppetlabs/puppet/ssl \
54-e PUPPETDB_HOST=<hostname> \
55-e PUPPETDB_PORT=8081 \
56-e PUPPETDB_SSL_VERIFY=/etc/puppetlabs/puppetdb/ssl/ca.pem \
57-e PUPPETDB_KEY=/etc/puppetlabs/puppetdb/ssl/private.pem \
58-e PUPPETDB_CERT=/etc/puppetlabs/puppetdb/ssl/public.pem \
59ghcr.io/voxpupuli/puppetboard
60```
61
62We also provide the Dockerfile so you can build the image yourself:
63```bash
64docker build -t puppetboard .
65```
66
67### From a package
68
69Actively maintained packages:
70
71* [FreeBSD](https://www.freshports.org/www/py-puppetboard/)
72 maintained by [Romain Tartière](https://github.com/smortex)
73* [OpenBSD](https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/www/puppetboard/)
74 maintained by [Sebastian Reitenbach](https://github.com/buzzdeee)
75
76### Manually
77
78You can also install the package from PyPI and configure a WSGI-capable application server to serve it.
79
80We recommend using virtualenv to provide a separate environment for the app.
81
82```bash
83virtualenv -p python3 venv
84. venv/bin/activate
85pip install puppetboard
86```
87
88Please see [an article about more deployment setups here](https://github.com/voxpupuli/puppetboard/blob/master/docs/Deployment-setups.md).
89
90## Configuration
91
92### PuppetDB
93
94Of course you need to configure your Puppet Server to store the Puppet run reports in PuppetDB.
95If you haven't done that already please follow the [PuppetDB documentation](https://puppet.com/docs/puppetdb/latest/connect_puppet_server.html)
96about this.
97
98If you run Puppetboard on a different host than PuppetDB then you may want to configure the certificate
99allow-list for which certificates are allowed to access data from PuppetDB.
100Please read more about this feature in the [PuppetDB documentation here](https://puppet.com/docs/puppetdb/latest/configure.html#certificate-allowlist).
101
102### App settings
103
104Puppetboard will look for a file pointed at by the `PUPPETBOARD_SETTINGS` environment variable.
105The file has to be identical to
106[default_settings.py](https://github.com/voxpupuli/puppetboard/blob/master/puppetboard/default_settings.py)
107but should only override the settings you need changed.
108
109If you run PuppetDB and Puppetboard on the same machine the default settings provided will be enough to get you started
110and you won't need a custom settings file.
111
112Assuming your webserver and PuppetDB machine are not identical you will at least have to change the following settings:
113
114- `PUPPETDB_HOST`
115- `PUPPETDB_PORT`
116
117By default PuppetDB requires SSL to be used when a non-local client wants to connect. Therefore you'll also have to
118supply the following settings:
119
120- `PUPPETDB_SSL_VERIFY = /path/to/ca/keyfile.pem`
121- `PUPPETDB_KEY = /path/to/private/keyfile.pem`
122- `PUPPETDB_CERT = /path/to/public/keyfile.crt`
123
124For information about how to generate the correct keys please refer to the
125[pypuppetdb documentation](https://pypuppetdb.readthedocs.io/en/latest/connecting.html#ssl). Alternatively it is possible
126to explicitly specify the protocol to be used setting the `PUPPETDB_PROTO` variable.
127
128Other settings that might be interesting in no particular order:
129
130- `SECRET_KEY`: Refer to [Flask documentation](https://flask.palletsprojects.com/en/1.1.x/quickstart/#sessions),
131 section "How to generate good secret keys" for more info. Defaults to a random 24-char string generated by
132 `os.random(24)`.
133- `PUPPETDB_TIMEOUT`: Defaults to 20 seconds but you might need to increase this value. It depends on how big the
134 results are when querying PuppetDB. This behaviour will change in a future release when pagination will be introduced.
135- `UNRESPONSIVE_HOURS`: The amount of hours since the last check-in after which a node is considered unresponsive.
136- `LOGLEVEL`: A string representing the loglevel. It defaults to `'info'` but can be changed to `'warning'` or
137 `'critical'` for less verbose logging or `'debug'` for more information.
138- `ENABLE_QUERY`: Defaults to `True` causing a Query tab to show up in the web interface allowing users to write
139 and execute arbitrary queries against a set of endpoints in PuppetDB. Change this to `False` to disable this.
140 See `ENABLED_QUERY_ENDPOINTS` to fine-tune which endpoints are allowed.
141- `ENABLED_QUERY_ENDPOINTS`: If `ENABLE_QUERY` is `True`, allow to fine tune the endpoints of PuppetDB APIs that
142 can be queried. It must be a list of strings of PuppetDB endpoints for which the query is enabled.
143 See the `QUERY_ENDPOINTS` constant in the `puppetboard.app` module for a list of the available endpoints.
144- `GRAPH_TYPE`: Specify the type of graph to display. Default is
145 pie, other good option is donut. Other choices can be found here:
146 \_C3JS\_documentation\`
147- `GRAPH_FACTS`: A list of fact names to tell PuppetBoard to generate a pie-chart on the fact page. With some fact
148 values being unique per node, like ipaddress, uuid, and serial number, as well as structured facts it was no longer
149 feasible to generate a graph for everything.
150- `INVENTORY_FACTS`: A list of tuples that serve as the column header and the fact name to search for to create
151 the inventory page. If a fact is not found for a node then `undef` is printed.
152- `ENABLE_CATALOG`: If set to `True` allows the user to view a node's latest catalog. This includes all managed
153 resources, their file-system locations and their relationships, if available. Defaults to `False`.
154- `REFRESH_RATE`: Defaults to `30` the number of seconds to wait until the index page is automatically refreshed.
155- `DEFAULT_ENVIRONMENT`: Defaults to `'production'`, as the name suggests, load all information filtered by this
156 environment value.
157- `REPORTS_COUNT`: Defaults to `10` the limit of the number of reports to load on the node or any reports page.
158- `OFFLINE_MODE`: If set to `True` load static assets (jquery, semantic-ui, etc) from the local web server instead
159 of a CDN. Defaults to `False`.
160- `DAILY_REPORTS_CHART_ENABLED`: Enable the use of daily chart graphs when looking at dashboard and node view.
161- `DAILY_REPORTS_CHART_DAYS`: Number of days to show history for on the daily report graphs.
162- `DISPLAYED_METRICS`: Metrics to show when displaying node summary. Example: `'resources.total'`, `'events.noop'`.
163- `TABLE_COUNT_SELECTOR`: Configure the dropdown to limit number of hosts to show per page.
164- `LITTLE_TABLE_COUNT`: Default number of reports to show when when looking at a node.
165- `NORMAL_TABLE_COUNT`: Default number of nodes to show when displaying reports and catalog nodes.
166- `LOCALISE_TIMESTAMP`: Normalize time based on localserver time.
167- `WITH_EVENT_NUMBERS`: If set to `True` then Overview and Nodes list shows exact number of changed resources
168 in the last report. Otherwise shows only 'some' string if there are resources with given status. Setting this
169 to `False` gives performance benefits, especially in big Puppet environments (more than few hundreds of nodes).
170 Defaults to `True`.
171- `DEV_LISTEN_HOST`: For use with dev.py for development. Default is localhost
172- `DEV_LISTEN_PORT`: For use with dev.py for development. Default is 5000
173
174## Getting Help
175
176For questions or bug reports you can file an [issue](https://github.com/voxpupuli/puppetboard/issues).
177
178## Contributing
179
180### Development
181
182Puppetboard relies on the [pypuppetdb](https://pypi.org/project/pypuppetdb/) library to fetch data from PuppetDB
183and is built with the help of the [Flask](https://flask.palletsprojects.com) microframework.
184
185If you wish to hack on Puppetboard you should fork/clone the Github repository and then install the requirements through:
186
187```bash
188pip install --upgrade wheel setuptools
189pip install --upgrade -r requirements-test.txt
190mypy --install-types --non-interactive puppetboard/ test/
191```
192
193You're advised to do this inside a virtualenv specifically created to work on Puppetboard as to not pollute your global Python installation.
194
195You can run the tests with:
196```bash
197pytest --cov=. --cov-report=xml --flake8 --strict-markers --mypy puppetboard test
198```
199
200You can run the app it in development mode by simply executing:
201
202```bash
203./dev.py
204```
205
206Use `PUPPETBOARD_SETTINGS` to change the different settings or patch `default_settings.py` directly.
207Take care not to include your local changes on that file when submitting patches for Puppetboard.
208Place a `settings.py` file inside the base directory of the git repository that will be used, if the environment
209variable is not set.
210
211We welcome contributions to this project. However, there are a few ground rules contributors should be aware of.
212
213### License
214
215This project is licensed under the Apache v2.0 License. As such, your contributions, once accepted, are automatically
216covered by this license.
217
218### Commit messages
219
220Write decent commit messages. Don't use swear words and refrain from uninformative commit messages as 'fixed typo'.
221
222The preferred format of a commit message:
223
224 docs/quickstart: Fixed a typo in the Nodes section.
225
226 If needed, elaborate further on this commit. Feel free to write a
227 complete blog post here if that helps us understand what this is
228 all about.
229
230 Fixes #4 and resolves #2.
231
232If you'd like a more elaborate guide on how to write and format your commit messages have a look at [this post
233by Tim Pope](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
234
235## More Screenshots
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257# Legal
258
259The app code is licensed under the [Apache License, Version 2.0](./LICENSE).
260
261The favicon has been created based on the icon created by [Jonathan Coutiño](https://thenounproject.com/ralts01/)
262under the [Attribution 3.0 Unported (CC BY 3.0) license](https://creativecommons.org/licenses/by/3.0/),
263downloaded from the [Noun Project](https://thenounproject.com).
264
/badge.svg)){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}