Mercurial > kallithea
changeset 5494:57caeb60c52b stable
docs: add documentation for setup with puppet
Incorporates feedback from Branko Majic and Søren Løvborg.
author | Robert Rauch <mail@robertrauch.de> |
---|---|
date | Thu, 03 Sep 2015 13:10:17 +0200 |
parents | 74fe92d7f5f3 |
children | 222a9f3d4023 |
files | README.rst docs/index.rst docs/installation_puppet.rst |
diffstat | 3 files changed, 184 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/README.rst Thu Sep 10 15:13:55 2015 +0000 +++ b/README.rst Thu Sep 03 13:10:17 2015 +0200 @@ -37,6 +37,13 @@ Please visit https://docs.kallithea-scm.org/en/latest/installation.html for more details. +There is also an experimental `Puppet module`_ for installing and setting up +Kallithea. Currently, only basic functionality is provided, but it is still +enough to get up and running quickly, especially for people without Python +background. See +https://docs.kallithea-scm.org/en/latest/installation_puppet.html for further +information. + Source code ----------- @@ -238,3 +245,4 @@ .. _Celery: http://celeryproject.org/ .. _vcs: http://pypi.python.org/pypi/vcs .. _Software Freedom Conservancy: http://sfconservancy.org/ +.. _Puppet module: https://forge.puppetlabs.com/rauch/kallithea
--- a/docs/index.rst Thu Sep 10 15:13:55 2015 +0000 +++ b/docs/index.rst Thu Sep 03 13:10:17 2015 +0200 @@ -22,6 +22,7 @@ installation_win_old installation_iis setup + installation_puppet **Usage**
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/installation_puppet.rst Thu Sep 03 13:10:17 2015 +0200 @@ -0,0 +1,175 @@ +.. _installation_puppet: + +=================================== +Installation and setup using Puppet +=================================== + +The whole installation and setup process of Kallithea can be simplified by +using Puppet and the `rauch/kallithea +<https://forge.puppetlabs.com/rauch/kallithea>`_ Puppet module. This is +especially useful for getting started quickly, without having to deal with all +the Python specialities. + +.. note:: The following instructions assume you are not familiar with Puppet at + all. If this is not the case, you should probably skip directly to the + `Kallithea Puppet module documentation + <https://forge.puppetlabs.com/rauch/kallithea#puppet-kallithea>`_. + + +Installing Puppet +----------------- + +This installation variant requires a Unix/Linux type server with Puppet 3.0+ +installed. Many major distributions have Puppet in their standard repositories. +Thus, you will probably be ready to go by running, e.g. ``apt-get install +puppet`` or ``yum install puppet``, depending on your distro's favoured package +manager. Afterwards, check the Puppet version by running ``puppet --version`` +and ensure you have at least 3.0. + +If your distribution does not provide Puppet packages or you need a +newer version, please see the `Puppet Reference Manual +<https://docs.puppetlabs.com/puppet/4.2/reference/install_linux.html>`_ for +instructions on how to install Puppet on your target platform. + + +Installing the Puppet module +---------------------------- + +To install the latest version of the Kallithea Puppet module from the Puppet +Forge, run the following as ``root``: + +.. code-block:: bash + + puppet module install rauch/kallithea + +This will install both the Kallithea Puppet module and its dependency modules. + +.. warning:: Be aware that Puppet can do all kinds of things to your systems. + Third-party modules (like the ``kallithea`` module) may run + arbitrary commands on your system (most of the time as the + ``root`` user), so do not apply them on production machines if + you don't know what you are doing. Instead, use a test system + (e.g. a virtual machine) for evaluation purposes. + + +Applying the module +------------------- + +To trigger the actual installation process, we have to *apply* the +``kallithea`` Puppet class, which is provided by the module we have just +installed, to our system. For this, create a file named e.g. ``kallithea.pp``, +a *Puppet manifest*, with the following content: + +.. _simple_manifest: +.. code-block:: puppet + + class { 'kallithea': + seed_db => true, + manage_git => true, + } + +To apply the manifest, simply run the following (preferably as root): + +.. code-block:: bash + + puppet apply kallithea.pp + +This will basically run through the usual Kallithea :ref:`installation` and +:ref:`setup` steps, as documented. Consult the module documentation for details +on `what the module affects +<https://forge.puppetlabs.com/rauch/kallithea#what-kallithea-affects>`_. You +can also do a *dry run* by adding the ``--noop`` option to the command. + + +Using parameters for customizing the setup process +-------------------------------------------------- + +The ``kallithea`` Puppet class provides a number of `parameters +<https://forge.puppetlabs.com/rauch/kallithea#class-kallithea>`_ for +customizing the setup process. You have seen the usage of the ``seed_db`` +parameter in the :ref:`example above <simple_manifest>`, but there are more. +For example, you can specify the installation directory, the name of the user +under which Kallithea gets installed, the initial admin password, etc. +Notably, you can provide arbitrary modifications to Kallitheas configuration +file by means of the ``config_hash`` parameter. + +Parameters, which have not been set explicitly, will be set to default values, +which are defined inside the ``kallithea`` Puppet module. For example, if you +just stick to the defaults as in the :ref:`example above <simple_manifest>`, +you will end up with a Kallithea instance, which + +- is installed in ``/srv/kallithea``, owned by the user ``kallithea`` +- uses the Kallithea default configuration +- uses the admin user ``admin`` with password ``adminpw`` +- is started automatically and enabled on boot + +As of Kallithea 0.3.0, this in particular means that Kallithea will use an +SQLite database and listen on ``http://localhost:5000``. + +See also the `full parameters list +<https://forge.puppetlabs.com/rauch/kallithea#class-kallithea>`_ for more +information. + + +Making your Kallithea instance publicly available +------------------------------------------------- + +If you followed the instructions above, the Kallithea instance will be +listening on ``http://localhost:5000`` and therefore not publicly available. +There are several ways to change this. + +The direct way +^^^^^^^^^^^^^^ + +The simplest setup is to instruct Kallithea to listen on another IP address +and/or port by using the ``config_hash`` parameter of the Kallithea Puppet +class. For example, assume we want to listen on all interfaces on port 80: + +.. code-block:: puppet + + class { 'kallithea': + seed_db => true, + config_hash => { + "server:main" => { + 'host' => '0.0.0.0', + 'port' => '80', + } + } + } + +Using Apache as reverse proxy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In a more advanced setup, you might instead want use a full-blown web server +like Apache HTTP Server as the public web server, configured such that requests +are internally forwarded to the local Kallithea instance (a so called *reverse +proxy setup*). This can be easily done with Puppet as well: + +First, install the `puppetlabs/apache +<https://forge.puppetlabs.com/puppetlabs/apache>`_ Puppet module as above by running the following as root: + +.. code-block:: bash + + puppet module install puppetlabs/apache + +Then, append the following to your manifest: + +.. code-block:: puppet + + include apache + + apache::vhost { 'kallithea.example.com': + docroot => '/var/www/html', + manage_docroot => false, + port => 80, + proxy_preserve_host => true, + proxy_pass => [ + { + path => '/', + url => 'http://localhost:5000/', + }, + ], + } + +Applying the resulting manifest will install the Apache web server and setup a +virtual host acting as a reverse proxy for your local Kallithea instance.