From 13bfffb34cd0385124d4084a66d49471cb457b6c Mon Sep 17 00:00:00 2001 From: Peter Wu Date: Sun, 10 Aug 2014 14:01:43 +0200 Subject: Add README file Documents requirements, installation instructions (obsoleting doc/INSTALL) and performance hints. Added a nginx server configuration example that optimises for performance. --- README.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/INSTALL | 3 --- doc/nginx.conf | 41 ++++++++++++++++++++++++++++++ 3 files changed, 119 insertions(+), 3 deletions(-) create mode 100644 README.md delete mode 100644 doc/INSTALL create mode 100644 doc/nginx.conf diff --git a/README.md b/README.md new file mode 100644 index 0000000..d4f3c52 --- /dev/null +++ b/README.md @@ -0,0 +1,78 @@ +Collectd Graph Panel (CGP) +========================== +Collectd Graph Panel (CGP) is a graphical web-based front-end for visualizing +RRD collected by [collectd][collectd], written in the PHP language. + +The latest version of CGP can be found on https://github.com/pommi/CGP. When you +have improvements or fixes, do not hesitate to send a pull request! + +Requirements +------------ +CGP has the following hard requirements: + + - Web server with PHP 5.0 support. + - `rrdtool` program, expected at `/usr/bin/rrdtool` (can be changed in the + configuration file, `$CONFIG['rrdtool']`). + - `shell_exec` must not be disabled through the [`disable_functions` ini + directive][ini.disable_functions]. It must allow execution of the `rrdtool` + program. + +The following software is optional, but nevertheless highly recommended: + + - [PHP JSON extension][php-json]: for a finer representation of the data in the + graph. These representations can be found in the `plugins/` directory. + - Web browser with `canvas` support such as IE 9+, Firefox, Chrome, Opera 9+. + Optional unless you use `$CONFIG['graph_type'] = 'canvas'`. + +Installation and configuration +------------------------------ +CGP is designed to run out of the box. If you want to modify some configuration +settings, please create `conf/config.local.php` to overrule the settings from +`conf/config.php`. + +In a default configuration, the server will execute `rrdtool` to draw PNG +graphs. These pictures are static and can put quite a burden on the server. For +more flexibility, set `$CONFIG['graph_type'] = 'canvas'`. This will make web +browsers download the RRD files and allows the user to zoom and move though the +history using their pointer device. + +See [doc/nginx.conf](doc/nginx.conf) for an example configuration for the nginx +web server. The `.htaccess` file in the top-level directory can serve as a guide +for Apache configuration. + +Performance tips +---------------- +Although the default configuration "just works", you can further improve your +set up to reduce data usage and CPU time: + + - Enable gzip compression and caching (for at least RRD data files, SVG + pictures and Javascript files. The canvas graph type downloads each RRD data + file which are quite large (considering their quantity). Savings of 70% - 80% + can be achieved for RRD data files. + - Set `$CONFIG['rrd_url']` to a directory directly accessible by the web server + such that it can provide better cache control than PHP. + - Instead of the default `png` graph type, consider `canvas` to relieve the web + server. This moves the image processing to the client that views the picture. + - Disable the `open_basedir` setting of PHP, or at least put the RRD data dir + in the beginning. When enabled, PHP (at least 5.5.14) scans though every + path component which is quite costly if you have over 100 RRD files and a + deep directory hierarchy. 17 seconds was observed for four path components + (with `.` at the end), this dropped down to 4.8 seconds when prepending the + RRD data directory to the beginning. When disabled, processing took less than + a second. + +License +------- +CGP is released under the terms of GPL version 3. See [doc/LICENSE](doc/LICENSE) +for the full license text. + +Acknowledgements +---------------- +CGP is authored by Pim van den Berg with contributions from many other people. + +Canvas support depends on jsrrdgraph by Manuel Luis, +https://github.com/manuelluis/jsrrdgraph + + [collectd]: http://collectd.org/ + [ini.disable_functions]: http://php.net/ini.core#ini.disable-functions + [php-json]: http://php.net/json diff --git a/doc/INSTALL b/doc/INSTALL deleted file mode 100644 index c0da959..0000000 --- a/doc/INSTALL +++ /dev/null @@ -1,3 +0,0 @@ -CGP is designed to run out of the box. If you want to modify some -configuration settings, please create conf/config.local.php to overrule -the settings from conf/config.php. diff --git a/doc/nginx.conf b/doc/nginx.conf new file mode 100644 index 0000000..d2efa46 --- /dev/null +++ b/doc/nginx.conf @@ -0,0 +1,41 @@ +server { + listen 80; + server_name localhost; + + root /srv/http; + index index.php; + + # This catches requests other than /CGP/rrd/ and PHP (see below) + location /CGP/ { + gzip on; + gzip_types "application/javascript text/css"; + # The static files do not change often, cache hint 1 month + expires 1M; + } + + # Assume that CGP is located at /srv/http/CGP/, directly serve the RRD data + # files for use with the canvas graph type. Add compression to reduce data + # usage by 70% - 80%. + location /CGP/rrd/ { + alias /var/lib/collectd/rrd/; + gzip on; + gzip_types "*"; + # Cache hint: browser can recheck after 10 minutes + expires 10m; + #gzip_comp_level 3; + } + + # Process PHP files through PHP-FPM + location ~ \.php$ { + try_files $uri =404; + fastcgi_pass unix:/run/php5-fpm.sock; + fastcgi_index index.php; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + include fastcgi_params; + } + + # Disallow access to hidden files and directories (such as .git/) + location ~ /\. { + deny all; + } +} -- cgit v1.1