@@ -13,26 +13,26 @@ installing Kallithea.
* A filesystem where the Mercurial and Git repositories can be stored.
* A database where meta data can be stored.
* A Python environment where the Kallithea application and its dependencies
can be installed.
* A web server that can host the Kallithea web application using the WSGI
API.
2. **Install Kallithea software.**
This makes the ``kallithea-cli`` command line tool available.
3. **Create low level configuration file.**
Use ``kallithea-cli config-create`` to create a ``.ini`` file with database
connection info, mail server information, some web server configuration,
etc.
connection info, mail server information, configuration for the specified
web server, etc.
4. **Populate the database.**
Use ``kallithea-cli db-create`` with the ``.ini`` file to create the
database schema and insert the most basic information: the location of the
repository store and an initial local admin user.
5. **Configure the web server.**
The web server must invoke the WSGI entrypoint for the Kallithea software
using the ``.ini`` file (and thus the database). This makes the web
application available so the local admin user can log in and tweak the
configuration further.
@@ -157,58 +157,64 @@ responsibility. Kallithea does however n
(protocol, address, port and path) for each HTTP request. Kallithea will
usually use its own HTML/cookie based authentication but can also be configured
to use web server authentication.
There are several web server options:
- Kallithea uses the Gearbox_ tool as command line interface. Gearbox provides
``gearbox serve`` as a convenient way to launch a Python WSGI / web server
from the command line. That is perfect for development and evaluation.
Actual use in production might have different requirements and need extra
work to make it manageable as a scalable system service.
Gearbox comes with its own built-in web server but Kallithea defaults to use
Waitress_. Gunicorn_ is also an option. These web servers have different
limited feature sets.
Gearbox comes with its own built-in web server for development but Kallithea
defaults to using Waitress_. Gunicorn_ and Gevent_ are also options. These
web servers have different limited feature sets.
The web server used by ``gearbox`` is configured in the ``.ini`` file passed
to it. The entry point for the WSGI application is configured
in ``setup.py`` as ``kallithea.config.middleware:make_app``.
The web server used by ``gearbox serve`` is configured in the ``.ini`` file.
Create it with ``config-create`` using for example ``http_server=waitress``
to get a configuration starting point for your choice of web server.
(Gearbox will do like ``paste`` and use the WSGI application entry point
``kallithea.config.middleware:make_app`` as specified in ``setup.py``.)
- `Apache httpd`_ can serve WSGI applications directly using mod_wsgi_ and a
simple Python file with the necessary configuration. This is a good option if
Apache is an option.
- uWSGI_ is also a full web server with built-in WSGI module.
- uWSGI_ is also a full web server with built-in WSGI module. Use
``config-create`` with ``http_server=uwsgi`` to get a ``.ini`` file with
uWSGI configuration.
- IIS_ can also server WSGI applications directly using isapi-wsgi_.
- A `reverse HTTP proxy <https://en.wikipedia.org/wiki/Reverse_proxy>`_
can be put in front of another web server which has WSGI support.
Such a layered setup can be complex but might in some cases be the right
option, for example to standardize on one internet-facing web server, to add
encryption or special authentication or for other security reasons, to
provide caching of static files, or to provide load balancing or fail-over.
Nginx_, Varnish_ and HAProxy_ are often used for this purpose, often in front
of a ``gearbox serve`` that somehow is wrapped as a service.
The best option depends on what you are familiar with and the requirements for
performance and stability. Also, keep in mind that Kallithea mainly is serving
dynamically generated pages from a relatively slow Python process. Kallithea is
also often used inside organizations with a limited amount of users and thus no
continuous hammering from the internet.
.. _Python: http://www.python.org/
.. _Gunicorn: http://gunicorn.org/
.. _Gevent: http://www.gevent.org/
.. _Waitress: http://waitress.readthedocs.org/en/latest/
.. _Gearbox: http://turbogears.readthedocs.io/en/latest/turbogears/gearbox.html
.. _PyPI: https://pypi.python.org/pypi
.. _Apache httpd: http://httpd.apache.org/
.. _mod_wsgi: https://code.google.com/p/modwsgi/
.. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi
.. _uWSGI: https://uwsgi-docs.readthedocs.org/en/latest/
.. _nginx: http://nginx.org/en/
.. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services
.. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29
.. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface
.. _HAProxy: http://www.haproxy.org/
Status change: