Mercurial > kallithea

annotate docs/overview.rst @ 6111:9c1fe6f96146

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
changelog: add evolve information to the graph and the mark unstable changesets in red based on that information
author domruf <dominikruf@gmail.com>
date Fri, 24 Jun 2016 19:30:27 +0200
parents 250f8150c4bb
children 8845ece50d51
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
1 .. _overview:
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
2
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
3 =====================
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
4 Installation overview
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
5 =====================
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
6
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
7 Some overview and some details that can help understanding the options when
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
8 installing Kallithea.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
9
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
10
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
11 Python environment
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
12 ------------------
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
13
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
14 **Kallithea** is written entirely in Python_ and requires Python version
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
15 2.6 or higher. Python 3.x is currently not supported.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
16
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
17 Given a Python installation, there are different ways of providing the
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
18 environment for running Python applications. Each of them pretty much
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
19 corresponds to a ``site-packages`` directory somewhere where packages can be
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
20 installed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
21
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
22 Kallithea itself can be run from source or be installed, but even when running
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
23 from source, there are some dependencies that must be installed in the Python
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
24 environment used for running Kallithea.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
25
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
26 - Packages *could* be installed in Python's ``site-packages`` directory ... but
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
27 that would require running pip_ as root and it would be hard to uninstall or
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
28 upgrade and is probably not a good idea unless using a package manager.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
29
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
30 - Packages could also be installed in ``~/.local`` ... but that is probably
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
31 only a good idea if using a dedicated user per application or instance.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
32
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
33 - Finally, it can be installed in a virtualenv_. That is a very lightweight
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
34 "container" where each Kallithea instance can get its own dedicated and
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
35 self-contained virtual environment.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
36
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
37 We recommend using virtualenv for installing Kallithea.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
38
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
39
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
40 Installation methods
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
41 --------------------
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
42
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
43 Kallithea must be installed on a server. Kallithea is installed in a Python
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
44 environment so it can use packages that are installed there and make itself
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
45 available for other packages.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
46
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
47 Two different cases will pretty much cover the options for how it can be
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
48 installed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
49
5435
60e04a21bf0f docs: more consistent use of --
Mads Kiilerich <madski@unity3d.com>
parents: 5433
diff changeset
50 - The Kallithea source repository can be cloned and used -- it is kept stable and
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
51 can be used in production. The Kallithea maintainers use the development
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
52 branch in production. The advantage of installation from source and regularly
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
53 updating it is that you take advantage of the most recent improvements. Using
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
54 it directly from a DVCS also means that it is easy to track local customizations.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
55
5755
250f8150c4bb docs: suggest using pip instead of setup.py develop
Andrew Shadura <andrew@shadura.me>
parents: 5435
diff changeset
56 Running ``pip install -e .`` in the source will use pip to install the
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
57 necessary dependencies in the Python environment and create a
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
58 ``.../site-packages/Kallithea.egg-link`` file there that points at the Kallithea
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
59 source.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
60
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
61 - Kallithea can also be installed from ready-made packages using a package manager.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
62 The official released versions are available on PyPI_ and can be downloaded and
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
63 installed with all dependencies using ``pip install kallithea``.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
64
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
65 With this method, Kallithea is installed in the Python environment as any
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
66 other package, usually as a ``.../site-packages/Kallithea-X-py2.7.egg/``
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
67 directory with Python files and everything else that is needed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
68
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
69 (``pip install kallithea`` from a source tree will do pretty much the same
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
70 but build the Kallithea package itself locally instead of downloading it.)
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
71
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
72
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
73 Web server
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
74 ----------
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
75
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
76 Kallithea is (primarily) a WSGI_ application that must be run from a web
5417
36a35394b3cb docs: fix some confusing paste/paster typos
Mads Kiilerich <madski@unity3d.com>
parents: 5413
diff changeset
77 server that serves WSGI applications over HTTP.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
78
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
79 Kallithea itself is not serving HTTP (or HTTPS); that is the web server's
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
80 responsibility. Kallithea does however need to know its own user facing URL
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
81 (protocol, address, port and path) for each HTTP request. Kallithea will
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
82 usually use its own HTML/cookie based authentication but can also be configured
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
83 to use web server authentication.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
84
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
85 There are several web server options:
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
86
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
87 - Kallithea uses the Paste_ tool as command line interface. Paste provides
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
88 ``paster serve`` as a convenient way to launch a Python WSGI / web server
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
89 from the command line. That is perfect for development and evaluation.
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
90 Actual use in production might have different requirements and need extra
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
91 work to make it manageable as a scalable system service.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
92
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
93 Paste comes with its own built-in web server but Kallithea defaults to use
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
94 Waitress_. Gunicorn_ is also an option. These web servers have different
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
95 limited feature sets.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
96
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
97 The web server used by ``paster`` is configured in the ``.ini`` file passed
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
98 to it. The entry point for the WSGI application is configured
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
99 in ``setup.py`` as ``kallithea.config.middleware:make_app``.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
100
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
101 - `Apache httpd`_ can serve WSGI applications directly using mod_wsgi_ and a
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
102 simple Python file with the necessary configuration. This is a good option if
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
103 Apache is an option.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
104
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
105 - uWSGI_ is also a full web server with built-in WSGI module.
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
106
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
107 - IIS_ can also server WSGI applications directly using isapi-wsgi_.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
108
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
109 - A `reverse HTTP proxy <https://en.wikipedia.org/wiki/Reverse_proxy>`_
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
110 can be put in front of another web server which has WSGI support.
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
111 Such a layered setup can be complex but might in some cases be the right
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
112 option, for example to standardize on one internet-facing web server, to add
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
113 encryption or special authentication or for other security reasons, to
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
114 provide caching of static files, or to provide load balancing or fail-over.
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
115 Nginx_, Varnish_ and HAProxy_ are often used for this purpose, often in front
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
116 of a ``paster`` server that somehow is wrapped as a service.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
117
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
118 The best option depends on what you are familiar with and the requirements for
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
119 performance and stability. Also, keep in mind that Kallithea mainly is serving
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
120 dynamically generated pages from a relatively slow Python process. Kallithea is
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
121 also often used inside organizations with a limited amount of users and thus no
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
122 continuous hammering from the internet.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
123
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
124
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
125 .. _Python: http://www.python.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
126 .. _Gunicorn: http://gunicorn.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
127 .. _Waitress: http://waitress.readthedocs.org/en/latest/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
128 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
129 .. _Paste: http://pythonpaste.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
130 .. _PyPI: https://pypi.python.org/pypi
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
131 .. _Apache httpd: http://httpd.apache.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
132 .. _mod_wsgi: https://code.google.com/p/modwsgi/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
133 .. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
134 .. _uWSGI: https://uwsgi-docs.readthedocs.org/en/latest/
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
135 .. _nginx: http://nginx.org/en/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
136 .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
137 .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
138 .. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
139 .. _pylons: http://www.pylonsproject.org/
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
140 .. _HAProxy: http://www.haproxy.org/
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
141 .. _Varnish: https://www.varnish-cache.org/