From 15185fa813c52152b0542a625fc517618b7e632a Mon Sep 17 00:00:00 2001 From: Piotr Date: Sat, 2 Feb 2019 21:34:09 +0100 Subject: [PATCH] Update and simplify docs --- conf/graphite.wsgi.example | 1 - docs/admin-carbon.rst | 13 -- docs/admin-webapp.rst | 19 --- docs/carbon-daemons.rst | 26 +++ ...base-setup.rst => config-webapp-setup.rst} | 27 +-- docs/config-webapp.rst | 76 ++++++--- docs/development.rst | 4 +- docs/faq.rst | 6 +- docs/index.rst | 2 - docs/install-pip.rst | 77 --------- docs/install-source.rst | 101 ----------- docs/install-virtualenv.rst | 75 -------- docs/install.rst | 161 ++++++++++++------ examples/example-graphite-vhost.conf | 9 +- 14 files changed, 218 insertions(+), 379 deletions(-) delete mode 100644 docs/admin-carbon.rst delete mode 100644 docs/admin-webapp.rst rename docs/{config-database-setup.rst => config-webapp-setup.rst} (83%) delete mode 100644 docs/install-pip.rst delete mode 100644 docs/install-source.rst delete mode 100644 docs/install-virtualenv.rst diff --git a/conf/graphite.wsgi.example b/conf/graphite.wsgi.example index c0f8f295a..2885aab5f 100755 --- a/conf/graphite.wsgi.example +++ b/conf/graphite.wsgi.example @@ -2,6 +2,5 @@ import sys # In case of multi-instance graphite, uncomment and set appropriate name # import os # os.environ['GRAPHITE_SETTINGS_MODULE'] = 'graphite.local_settings' -sys.path.append('/opt/graphite/webapp') from graphite.wsgi import application diff --git a/docs/admin-carbon.rst b/docs/admin-carbon.rst deleted file mode 100644 index b5a7acc51..000000000 --- a/docs/admin-carbon.rst +++ /dev/null @@ -1,13 +0,0 @@ -Administering Carbon -==================== - - -Starting Carbon ---------------- -Carbon can be started with the ``carbon-cache.py`` script:: - - /opt/graphite/bin/carbon-cache.py start - -This starts the main Carbon daemon in the background. Now is a good time -to check the logs, located in ``/opt/graphite/storage/log/carbon-cache/`` -for any errors. diff --git a/docs/admin-webapp.rst b/docs/admin-webapp.rst deleted file mode 100644 index 7a3f52826..000000000 --- a/docs/admin-webapp.rst +++ /dev/null @@ -1,19 +0,0 @@ -Administering The Webapp -======================== - -Depending on the stack you choose to expose the Graphite webapp, its usage varies slightly. - -nginx + gunicorn ----------------- - -As nginx is already ready to proxy requests, we just need to start Gunicorn. - -The following will do: - -.. code-block:: none - - PYTHONPATH=/opt/graphite/webapp gunicorn wsgi --workers=4 --bind=127.0.0.1:8080 --log-file=/var/log/gunicorn.log --preload --pythonpath=/opt/graphite/webapp/graphite & - -It will start Gunicorn and listen on ``localhost:8080``, log to ``/var/log/gunicorn.log`` and use ``/opt/graphite/webapp/graphite`` as the webapp path. - -Naturally, you can change these settings so that it fits your setup. diff --git a/docs/carbon-daemons.rst b/docs/carbon-daemons.rst index a10f46d8e..5b6446b1c 100644 --- a/docs/carbon-daemons.rst +++ b/docs/carbon-daemons.rst @@ -13,6 +13,32 @@ the data once they receive it. This document gives a brief overview of what each does and how you can use them to build a more sophisticated storage backend. +Starting and stopping Carbon +---------------------------- + +To start the Carbon daemons run: + +.. code-block:: bash + + carbon-cache.py start + carbon-relay.py start + carbon-aggregator.py start + carbon-aggregator-cache.py start + + +.. note:: If you are using Virtualenv you must specify the full path + ``/opt/graphite/bin/carbon-cache.py start`` + +To stop the daemons replace ``start`` with ``stop``. + + +Logs +---- + +If installed in the :ref:`default location ` then the +Carbon daemons write their logs to ``/opt/graphite/storage/log/``. + + carbon-cache.py --------------- diff --git a/docs/config-database-setup.rst b/docs/config-webapp-setup.rst similarity index 83% rename from docs/config-database-setup.rst rename to docs/config-webapp-setup.rst index 18ec781ff..7c11724fa 100644 --- a/docs/config-database-setup.rst +++ b/docs/config-webapp-setup.rst @@ -1,14 +1,15 @@ -Webapp Database Setup -===================== +Webapp Setup +============ + +Before Graphite-web can be started the database needs to be initialized and the static files need to be collected. + +Database Setup +-------------- + You must tell Django to create the database tables used by the graphite webapp. This is very straight forward, especially if you are using the default SQLite setup. The following configures the Django database settings. Graphite uses the database for storing user profiles, dashboards, and for the Events functionality. Graphite uses an SQLite database file located at ``STORAGE_DIR/graphite.db`` by default. If running multiple Graphite-web instances, a database such as PostgreSQL or MySQL is required so that all instances may share the same data source. -.. note :: - As of Django 1.2, the database configuration is specified by the DATABASES - dictionary instead of the old ``DATABASE_*`` format. Users must use the new - specification to have a working database. - See the `Django documentation `_ for full documentation of the DATABASES setting. @@ -20,15 +21,21 @@ To set up a new database and create the initial schema, run: .. code-block:: none - PYTHONPATH=$GRAPHITE_ROOT/webapp django-admin.py migrate --settings=graphite.settings + django-admin.py migrate --settings=graphite.settings + +.. note:: + + If you get a ``Could not import settings 'graphite.settings'`` error message add your ``PYTHONPATH`` in front of the command: + ``PYTHONPATH=$GRAPHITE_ROOT/webapp django-admin.py migrate --settings=graphite.settings`` .. note :: Graphite-Web 1.0 and earlier had some models without migrations, and with Django 1.9 or later, the ``--run-syncdb`` option was needed for migrate to create tables for these models. (Django 1.8 and earlier did not have this option, but always exhibited this behavior.) In Graphite-Web 1.1 and later all models have migrations, so ``--run-syncdb`` is no longer needed. If upgrading a database created by Graphite-Web 1.0 or earlier, you need to use the ``--fake-initial`` option for migrate: it considers an initial migration to already be applied if the tables it creates already exist. + If you are experiencing problems, uncomment the following line in /opt/graphite/webapp/graphite/local_settings.py: .. code-block:: none - + # DEBUG = True and review your webapp logs. If you're using the default graphite-example-vhost.conf, your logs will be found in /opt/graphite/storage/log/webapp/. @@ -36,5 +43,5 @@ and review your webapp logs. If you're using the default graphite-example-vhost. If you're using the default SQLite database, your webserver will need permissions to read and write to the database file. So, for example, if your webapp is running in Apache as the 'nobody' user, you will need to fix the permissions like this: .. code-block:: none - + sudo chown nobody:nobody /opt/graphite/storage/graphite.db diff --git a/docs/config-webapp.rst b/docs/config-webapp.rst index e5d4752f1..826158297 100644 --- a/docs/config-webapp.rst +++ b/docs/config-webapp.rst @@ -31,6 +31,53 @@ On Debian-based systems, run: sudo apt install gunicorn +Next, you will have to create a configuration to start Graphite. +If your system is using Systemd create following unit files: + +``/etc/systemd/system/graphite-web.socket``: + +.. code-block:: none + + [Unit] + Description=Graphite-web socket + + [Socket] + ListenStream=/run/graphite-web.sock + ListenStream=127.0.0.1:8080 + + [Install] + WantedBy=sockets.target + +``/etc/systemd/system/graphite-web.service``: + +.. code-block:: none + + [Unit] + Description=Graphite-web service + Requires=graphite-web.socket + + [Service] + ExecStart=/usr/bin/gunicorn -w2 graphite.wsgi -b 127.0.0.1:8080 + # If you are using virtualenv specify the path to gunicorn in virtualenv. + # ExecStart=/opt/graphite/bin/gunicorn -w2 graphite.wsgi -b 127.0.0.1:8080 + Restart=on-failure + #User=graphite + #Group=graphite + ExecReload=/bin/kill -s HUP $MAINPID + ExecStop=/bin/kill -s TERM $MAINPID + PrivateTmp=true + + [Install] + WantedBy=multi-user.target + + +Reload the systemd configuration, the service is socket activated so no need to start it manually. + +.. code-block:: none + + systemctl daemon-reload + + Install nginx ^^^^^^^^^^^^^ @@ -40,9 +87,6 @@ On Debian-based systems, run: sudo apt install nginx -Configure nginx -^^^^^^^^^^^^^^^ - We will use dedicated log files for nginx when serving Graphite: .. code-block:: none @@ -74,12 +118,6 @@ Write the following configuration in ``/etc/nginx/sites-available/graphite``: return 204; } - # serve static content from the "content" directory - location /static { - alias /opt/graphite/webapp/content; - expires max; - } - location / { try_files $uri @graphite; } @@ -144,6 +182,9 @@ Finally, configure the apache vhost. (You can find example of Graphite vhost con LoadModule wsgi_module modules/mod_wsgi.so + # Set WSGIPythonHome when using virtualenv + # WSGIPythonHome /opt/graphite + WSGISocketPrefix /var/run/wsgi Listen 80 @@ -161,18 +202,6 @@ Finally, configure the apache vhost. (You can find example of Graphite vhost con WSGIScriptAlias / /opt/graphite/conf/graphite.wsgi - Alias /static/ /opt/graphite/static/ - - - - Order deny,allow - Allow from all - - = 2.4> - Require all granted - - - Order deny,allow @@ -184,6 +213,9 @@ Finally, configure the apache vhost. (You can find example of Graphite vhost con + +.. note:: You have to configure ``WSGIPythonHome`` if you are using Virtualenv + Adapt the mod_wsgi configuration to your requirements. See the `mod_wsgi QuickConfigurationGuide`_ for an overview of configurations and `mod_wsgi ConfigurationDirectives`_ to see all configuration directives @@ -272,7 +304,7 @@ Enable the vhost and restart nginx: Acnowlegments -------------_ +------------- Portions of that manual are based on `Graphite-API deployment manual`_. diff --git a/docs/development.rst b/docs/development.rst index 7281bc53b..b04671780 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -5,8 +5,8 @@ Graphite-web accepts contributions on `GitHub `_, in the form of issues or pull requests. If you're comfortable with Python, here is how to get started. -First, keep in mind that Graphite-web supports Python versions **2.6 to 2.7** -and Django versions **1.4 and above**. +First, keep in mind that Graphite-web supports Python versions **2.7 and above** +and Django versions **1.8 and above**. Setting up a development environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/faq.rst b/docs/faq.rst index 7dc8c4c85..d2752b665 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -3,7 +3,7 @@ FAQ What is Graphite? ----------------- -Graphite is a highly scalable real-time graphing system. As a user, you write an application that collects numeric time-series data that you are interested in graphing, and send it to Graphite's processing backend, :doc:`carbon `, which stores the data in Graphite's specialized database. The data can then be visualized through graphite's web interfaces. +Graphite is a highly scalable real-time graphing system. As a user, you write an application that collects numeric time-series data that you are interested in graphing, and send it to Graphite's processing backend, :doc:`carbon `, which stores the data in Graphite's specialized database. The data can then be visualized through Graphite's web interfaces. Who should use Graphite? @@ -35,7 +35,7 @@ Graphite was internally developed by `Orbitz`_ where it is used to visualize a v What is Graphite written in? ---------------------------- -Python2. The Graphite webapp is built on the `Django`_ web framework and uses the ExtJS javascript GUI toolkit. The graph rendering is done using the Cairo graphics library. The backend and database are written in pure Python. +Python. The Graphite webapp is built on the `Django`_ web framework and uses the ExtJS javascript GUI toolkit. The graph rendering is done using the Cairo graphics library. The backend and database are written in pure Python. Who writes and maintains Graphite? @@ -76,7 +76,7 @@ Is there a diagram of Graphite's architecture? ---------------------------------------------- There sure is! Here it is: -.. image:: ../webapp/content/img/overview.png +.. image:: ../webapp/graphite/static/img/overview.png .. _Django: http://www.djangoproject.com/ diff --git a/docs/index.rst b/docs/index.rst index 6652f408e..b6e0329d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,10 +11,8 @@ Graphite Documentation carbon-daemons config-carbon feeding-carbon - admin-carbon config-local-settings config-webapp - admin-webapp composer render_api functions diff --git a/docs/install-pip.rst b/docs/install-pip.rst deleted file mode 100644 index c845e3957..000000000 --- a/docs/install-pip.rst +++ /dev/null @@ -1,77 +0,0 @@ -Installing From Pip -=================== - -Versioned Graphite releases can be installed via `pip `_. When installing with pip, installation of Python package dependencies will automatically be attempted. - -.. note:: - - In order to install Graphite-Web and Carbon, you must first install some development headers. In Debian-based distributions, this will require ``apt-get install python-dev libcairo2-dev libffi-dev build-essential``, and in Red Hat-based distributions you will run ``yum install python-devel cairo-devel libffi-devel``. - -Installing in the Default Location ----------------------------------- -To install Graphite in the :ref:`default location `, ``/opt/graphite/``, -simply execute as root: - -.. code-block:: none - - export PYTHONPATH="/opt/graphite/lib/:/opt/graphite/webapp/" - pip install --no-binary=:all: https://github.com/graphite-project/whisper/tarball/master - pip install --no-binary=:all: https://github.com/graphite-project/carbon/tarball/master - pip install --no-binary=:all: https://github.com/graphite-project/graphite-web/tarball/master - -.. note:: - - If your version of ``pip`` is < 7.0.0 then no need to use ``--no-binary=:all:`` parameter - -.. note:: - - On RedHat-based systems using the ``python-pip`` package, the pip executable is named ``pip-python`` - -Installing Carbon in a Custom Location --------------------------------------- -Installation of Carbon in a custom location with `pip` is similar to doing so from a source install. Arguments to the underlying ``setup.py`` controlling installation location can be passed through `pip` with the ``--install-option`` option. - -See :ref:`carbon-custom-location-source` for details of locations and available arguments - -For example, to install everything in ``/srv/graphite/``: - -.. code-block:: none - - pip install https://github.com/graphite-project/carbon/tarball/master --install-option="--prefix=/srv/graphite" --install-option="--install-lib=/srv/graphite/lib" - -To install Carbon into the system-wide site-packages directory with scripts in ``/usr/bin`` and storage and -configuration in ``/usr/share/graphite``: - -.. code-block:: none - - pip install https://github.com/graphite-project/carbon/tarball/master --install-option="--install-scripts=/usr/bin" --install-option="--install-lib=/usr/lib/python2.6/site-packages" --install-option="--install-data=/var/lib/graphite" - -Installing Graphite-web in a Custom Location --------------------------------------------- -Installation of Graphite-web in a custom location with `pip` is similar to doing so from a source install. -Arguments to the underlying ``setup.py`` controlling installation location can be passed through `pip` -with the ``--install-option`` option. - -See :ref:`graphite-web-custom-location-source` for details on default locations and available arguments - -For example, to install everything in ``/srv/graphite/``: - -.. code-block:: none - - pip install https://github.com/graphite-project/graphite-web/tarball/master --install-option="--prefix=/srv/graphite" --install-option="--install-lib=/srv/graphite/webapp" - -To install the Graphite-web code into the system-wide site-packages directory with scripts in -``/usr/bin`` and storage configuration, and content in ``/usr/share/graphite``: - -.. code-block:: none - - pip install https://github.com/graphite-project/graphite-web/tarball/master --install-option="--install-scripts=/usr/bin" --install-option="--install-lib=/usr/lib/python2.6/site-packages" --install-option="--install-data=/var/lib/graphite" - -Installing Ceres ----------------- -Ceres is an alternative storage backend that some choose to use in place of the default Whisper backend. - -.. code-block:: none - - pip install https://github.com/graphite-project/ceres/tarball/master - diff --git a/docs/install-source.rst b/docs/install-source.rst deleted file mode 100644 index 6187cce4a..000000000 --- a/docs/install-source.rst +++ /dev/null @@ -1,101 +0,0 @@ -Installing From Source -====================== -The latest source tarballs for Graphite-web, Carbon, and Whisper may be fetched from the Graphite -project `download page`_ or the latest development branches may be cloned from the `Github project page`_: - -* Graphite-web: ``git clone https://github.com/graphite-project/graphite-web.git`` -* Carbon: ``git clone https://github.com/graphite-project/carbon.git`` -* Whisper: ``git clone https://github.com/graphite-project/whisper.git`` -* Ceres: ``git clone https://github.com/graphite-project/ceres.git`` - -.. note:: - - There currently is no tarball available for Ceres, it must be cloned from the - `Github project page`_ - - -Installing in the Default Location ----------------------------------- -To install Graphite in the :ref:`default location `, ``/opt/graphite/``, simply execute -``python setup.py install`` as root in each of the project directories for Graphite-web, Carbon, Whisper, and Ceres. - -.. _carbon-custom-location-source: - -Installing Carbon in a Custom Location --------------------------------------- -Carbon's ``setup.py`` installer is configured to use a ``prefix`` of ``/opt/graphite`` and an -``install-lib`` of ``/opt/graphite/lib``. Carbon's lifecycle wrapper scripts and utilities -are installed in ``bin``, configuration within ``conf``, and stored data in ``storage`` all within ``prefix``. -These may be overridden by passing parameters to the ``setup.py install`` command. - -The following parameters influence the install location: - -- ``--prefix`` - - Location to place the ``bin/`` and ``storage/`` and ``conf/`` directories (defaults to ``/opt/graphite/``) - -- ``--install-lib`` - - Location to install Python modules (default: ``/opt/graphite/lib``) - -- ``--install-data`` - - Location to place the ``storage`` and ``conf`` directories (default: value of ``prefix``) - -- ``--install-scripts`` - - Location to place the scripts (default: ``bin/`` inside of ``prefix``) - - -For example, to install everything in ``/srv/graphite/``: - -.. code-block:: none - - python setup.py install --prefix=/srv/graphite --install-lib=/srv/graphite/lib - -To install Carbon into the system-wide site-packages directory with scripts in ``/usr/bin`` and storage and -configuration in ``/usr/share/graphite``: - -.. code-block:: none - - python setup.py install --install-scripts=/usr/bin --install-lib=/usr/lib/python2.6/site-packages --install-data=/var/lib/graphite - -.. _graphite-web-custom-location-source: - -Installing Graphite-web in a Custom Location --------------------------------------------- -Graphite-web's ``setup.py`` installer is configured to use a ``prefix`` of ``/opt/graphite`` and an ``install-lib`` of ``/opt/graphite/webapp``. Utilities are installed in ``bin``, and configuration in ``conf`` within the ``prefix``. These may be overridden by passing parameters to ``setup.py install`` - -The following parameters influence the install location: - -- ``--prefix`` - - Location to place the ``bin/`` and ``conf/`` directories (defaults to ``/opt/graphite/``) - -- ``--install-lib`` - - Location to install Python modules (default: ``/opt/graphite/webapp``) - -- ``--install-data`` - - Location to place the ``webapp/content`` and ``conf`` directories (default: value of ``prefix``) - -- ``--install-scripts`` - - Location to place scripts (default: ``bin/`` inside of ``prefix``) - - -For example, to install everything in ``/srv/graphite/``: - -.. code-block:: none - - python setup.py install --prefix=/srv/graphite --install-lib=/srv/graphite/webapp - -To install the Graphite-web code into the system-wide site-packages directory with scripts in ``/usr/bin`` and storage configuration, and content in ``/usr/share/graphite``: - -.. code-block:: none - - python setup.py install --install-scripts=/usr/bin --install-lib=/usr/lib/python2.6/site-packages --install-data=/var/lib/graphite - -.. _Github project page: http://github.com/graphite-project -.. _download page: https://launchpad.net/graphite/+download diff --git a/docs/install-virtualenv.rst b/docs/install-virtualenv.rst deleted file mode 100644 index 536483b86..000000000 --- a/docs/install-virtualenv.rst +++ /dev/null @@ -1,75 +0,0 @@ -Installing in Virtualenv -======================== -`Virtualenv`_ provides an isolated Python environment to run Graphite in. - -Installing in the Default Location ----------------------------------- -To install Graphite in the :ref:`default location `, ``/opt/graphite/``, -create a virtualenv in ``/opt/graphite`` and activate it: - -.. code-block:: none - - virtualenv /opt/graphite - source /opt/graphite/bin/activate - -Once the virtualenv is activated, Graphite and Carbon can be installed -:doc:`from source ` or :doc:`via pip `. Note that dependencies will -need to be installed while the virtualenv is activated unless -`--system-site-packages `_ -is specified at virtualenv creation time. - -Installing in a Custom Location -------------------------------- -To install from source activate the virtualenv and see the instructions for :ref:`graphite-web ` and :ref:`carbon ` - -Running Carbon Within Virtualenv --------------------------------- -Carbon may be run within Virtualenv by `activating virtualenv`_ before Carbon is started - -Running Graphite-web Within Virtualenv --------------------------------------- -Running Django's ``django-admin.py`` within a virtualenv requires using the -full path of the virtualenv:: - - /path/to/env/bin/django-admin.py --settings=graphite.settings - -The method of running Graphite-web within Virtualenv depends on the WSGI server used: - -Apache mod_wsgi -^^^^^^^^^^^^^^^ -.. note:: - - The version Python used to compile mod_wsgi must match the Python installed in the virtualenv (generally the system Python) - -To the Apache `mod_wsgi`_ config, add the root of the virtualenv as ``WSGIPythonHome``, ``/opt/graphite`` -in this example: - -.. code-block:: none - - WSGIPythonHome /opt/graphite - -and add the virtualenv's python site-packages to the ``graphite.wsgi`` file, python 2.6 in ``/opt/graphite`` -in this example: - -.. code-block:: none - - site.addsitedir('/opt/graphite/lib/python2.6/site-packages') - -See the `mod_wsgi documentation on Virtual Environments ` for more details. - -Gunicorn -^^^^^^^^ -Ensure `Gunicorn`_ is installed in the activated virtualenv and execute as normal. If gunicorn is -installed system-wide, it may be necessary to execute it from the virtualenv's bin path - -uWSGI -^^^^^ -Execute `uWSGI`_ using the ``-H`` option to specify the virtualenv root. See the `uWSGI documentation on virtualenv `_ for more details. - - -.. _activating virtualenv: http://www.virtualenv.org/en/latest/index.html#activate-script -.. _Gunicorn: http://gunicorn.org/ -.. _mod_wsgi: http://code.google.com/p/modwsgi/ -.. _uWSGI: http://projects.unbit.it/uwsgi -.. _Virtualenv: http://virtualenv.org/ - diff --git a/docs/install.rst b/docs/install.rst index 352b1d2ee..b3c7683cb 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,12 +1,18 @@ Installing Graphite =================== +There are several ways to install Graphite. Docker is the easiest way and is recommended for new +users. If you need to install Graphite directly on your system (not using Docker) then using +`Virtualenv`_ with `pip`_ would be recommended. With virtualenv all dependencies are installed +isolated so they will not interfere with your system Python. Installation from source should +only be used in specific cases (e.g. installing a development release). + Docker ------ Try Graphite in Docker and have it running in seconds: -.. code-block:: none +.. code-block:: bash docker run -d\ --name graphite\ @@ -33,19 +39,19 @@ been met or not. Basic Graphite requirements: * a UNIX-like Operating System -* Python 2.7 or greater (including experimental Python3 support) +* Python 2.7 or greater (including Python 3) * `cairocffi`_ -* `Django`_ 1.8 - 1.11 (for Python3 - 1.11 only) +* `Django`_ 1.8 - 2.1 * `django-tagging`_ 0.4.6 (not `django-taggit` yet) * `pytz`_ * `scandir`_ * `fontconfig`_ and at least one font package (a system package usually) * A WSGI server and web server. Popular choices are: - - `Apache`_ with `mod_wsgi`_ - - `gunicorn`_ with `nginx`_ + - `Apache`_ with `mod_wsgi`_ + - `uWSGI`_ with `nginx`_ Additionally, the Graphite webapp and Carbon require the Whisper database library which @@ -57,7 +63,9 @@ There are also several other dependencies required for additional features: * LDAP authentication: `python-ldap`_ (for LDAP authentication support in the webapp) * AMQP support: `txamqp`_ (version 0.8 is required) * RRD support: `python-rrdtool`_ -* Dependent modules for additional database support (MySQL, PostgreSQL, etc). See `Django database install`_ instructions and the `Django database`_ documentation for details +* Dependent modules for additional database support (MySQL, PostgreSQL, etc). See + `Django database install`_ instructions and the `Django database`_ documentation for details +* `pyhash`_ fnv1_ch hashing support .. seealso:: On some systems it is necessary to install fonts for Cairo to use. If the webapp is running but all graphs return as broken images, this may be why. @@ -69,75 +77,123 @@ There are also several other dependencies required for additional features: Fulfilling Dependencies ----------------------- Most current Linux distributions have all of the requirements available in the base packages. -RHEL based distributions may require the `EPEL`_ repository for requirements. -Python module dependencies can be install with `pip`_ rather than system packages if desired or if using -a Python version that differs from the system default. Some modules (such as Cairo) may require -library development headers to be available. +Python module dependencies can be install with `pip`_ rather than system packages if desired +or if using a Python version that differs from the system default. Some modules (such as Cairo) +may require library development headers to be available. + + +RHEL/Centos 7 +^^^^^^^^^^^^^ +For RHEL based distributions enable the `EPEL`_ repository. + +.. code-block:: bash + + yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm + yum install dejavu-sans-fonts dejavu-serif-fonts python-pip python-virtualenv cairo + +Debian-based distributions +^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. code-block:: bash + + apt-get install python-dev libcairo2-dev libffi-dev build-essential .. _default-installation-layout : Default Installation Layout --------------------------- -Graphite defaults to an installation layout that puts the entire install in its own directory: ``/opt/graphite`` - -Whisper -^^^^^^^ -Whisper is installed Python's system-wide site-packages directory with Whisper's utilities installed -in the bin dir of the system's default prefix (generally ``/usr/bin/``). +Graphite traditionally installed all components in ``/opt/graphite``, since release 1.2.0 +Graphite's installation location depends on your `Python prefix`_. If you are using `Virtualenv`_ +the ``prefix`` is set to the root of your virtualenv. You can find your ``prefix`` by running: -Carbon and Graphite-web -^^^^^^^^^^^^^^^^^^^^^^^ -Carbon and Graphite-web are installed in ``/opt/graphite/`` with the following layout: +.. code-block:: bash -- ``bin/`` -- ``conf/`` -- ``lib/`` + python -c 'import sys; print(sys.prefix)' - Carbon ``PYTHONPATH`` +Directory layout: -- ``storage/`` +- ``PREFIX/`` Usually ``/opt/graphite/`` - - ``log`` + - ``conf/`` Carbon configuration files - Log directory for Carbon and Graphite-web + - ``storage/`` - - ``rrd`` + - ``log`` Log directory for Carbon and Graphite-web - Location for RRD files to be read + - ``rrd`` Location for RRD files to be read - - ``whisper`` + - ``whisper`` Location for Whisper data files to be stored and read - Location for Whisper data files to be stored and read + - ``ceres`` Location for Ceres data files to be stored and read - - ``ceres`` - Location for Ceres data files to be stored and read +.. note:: Graphite-web's config file `local_settings.py` is located in the project + :doc:`directory ` -- ``webapp/`` +Using Virtualenv +---------------- +`Virtualenv`_ provides an isolated Python environment to run Graphite in. It is recommended to +install Graphite in Virtualenv so that dependent libraries will not interfere with other +applications. - Graphite-web ``PYTHONPATH`` +Create a virtualenv in ``/opt/graphite`` and activate it: - - ``graphite/`` +.. code-block:: bash - Location of ``local_settings.py`` + virtualenv /opt/graphite + source /opt/graphite/bin/activate - - ``content/`` +Once the virtualenv is activated, Graphite and Carbon can be installed the regular way +:ref:`via pip ` or :ref:`from source `. - Graphite-web static content directory +.. note:: Before installing dependencies or running Graphite the virtualenv needs to be + activated. Deactivating virtualenv can be done by running ``deactivate``. +.. _install-pip : -Installing Graphite +Installing From Pip ------------------- -Several installation options exist: -.. toctree:: - :maxdepth: 2 +Versioned Graphite releases can be installed via `pip`_. When installing with pip, +installation of Python package dependencies will automatically be attempted. - install-source - install-pip - install-virtualenv +To install Graphite execute: +.. code-block:: bash + + pip install whisper + pip install carbon + pip install graphite-web + +.. _install-source : + +Installing From Source +---------------------- + +The latest source tarballs for Graphite-web, Carbon, and Whisper may be fetched from the +Graphite project `download page`_ or the latest development branches may be cloned from +the `Github project page`_: + +.. code-block:: bash + + git clone https://github.com/graphite-project/whisper.git + git clone https://github.com/graphite-project/carbon.git + git clone https://github.com/graphite-project/graphite-web.git + + +To install with pip (which will automatically install dependent Python libraries): + +.. code-block:: bash + + pip install ./whisper/ + pip install ./carbon/ + pip install ./graphite-web/ + +Or without using pip, run from every directory: + +.. code-block:: bash + + python setup.py install --single-version-externally-managed Initial Configuration --------------------- @@ -145,7 +201,7 @@ Initial Configuration .. toctree:: :maxdepth: 2 - config-database-setup + config-webapp-setup config-webapp config-local-settings config-carbon @@ -166,9 +222,6 @@ Post-Install Tasks Initially none of the config files are created by the installer but example files are provided. Simply copy the ``.example`` files and customize. -:doc:`Administering Carbon ` - Once Carbon is configured, you need to start it up. - :doc:`Feeding In Your Data ` Once it's up and running, you need to feed it some data. @@ -176,9 +229,6 @@ Post-Install Tasks With data getting into carbon, you probably want to look at graphs of it. So now we turn our attention to the webapp. -:doc:`Administering The Webapp ` - Once its configured you'll need to get it running. - :doc:`Using the Composer ` Now that the webapp is running, you probably want to learn how to use it. @@ -201,7 +251,7 @@ Unfortunately, native Graphite on Windows is unsupported, but you can run Graphi .. _mod_wsgi: https://modwsgi.readthedocs.io/ .. _nginx: http://nginx.org/ .. _NOT Python 3: https://python3wos.appspot.com/ -.. _pip: https://pip.pypa.io/ +.. _pip: https://pypi.org/project/pip/ .. _python-ldap: https://www.python-ldap.org/ .. _python-memcache: https://www.tummy.com/software/python-memcached/ .. _python-rrdtool: http://oss.oetiker.ch/rrdtool/prog/rrdpython.en.html @@ -212,3 +262,8 @@ Unfortunately, native Graphite on Windows is unsupported, but you can run Graphi .. _uWSGI: http://uwsgi-docs.readthedocs.io/ .. _Docker: https://www.docker.com/ .. _docker repo: https://github.com/graphite-project/docker-graphite-statsd +.. _Virtualenv: http://virtualenv.org/ +.. _Github project page: http://github.com/graphite-project +.. _download page: https://launchpad.net/graphite/+download +.. _pyhash: https://pypi.org/project/pyhash/ +.. _Python prefix: https://docs.python.org/3/library/sys.html#sys.prefix diff --git a/examples/example-graphite-vhost.conf b/examples/example-graphite-vhost.conf index 6b78ca8ca..ac09fce40 100644 --- a/examples/example-graphite-vhost.conf +++ b/examples/example-graphite-vhost.conf @@ -15,6 +15,13 @@ LoadModule wsgi_module modules/mod_wsgi.so +# Virtualenv +# You have to set WSGIPythonHome to the root of your virtualenv installation +# when you are using virtualenv +# +# WSGIPythonHome /opt/graphite + + # XXX You need to set this up! # Read http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGISocketPrefix # For example, create a directory /var/run/wsgi and use that. @@ -43,7 +50,7 @@ WSGISocketPrefix run/wsgi # * Collect static files in a directory by running: # django-admin.py collectstatic --noinput --settings=graphite.settings # And set an alias to serve static files with Apache: - Alias /static/ /opt/graphite/static/ + # Alias /static/ /opt/graphite/static/ ######################## # URL-prefixed install #