Mercurial > kallithea
comparison docs/overview.rst @ 5081:154becd92f40
docs: add installation overview section
author | Mads Kiilerich <madski@unity3d.com> |
---|---|
date | Tue, 07 Apr 2015 02:53:04 +0200 |
parents | |
children | 22a3fa3c4254 |
comparison
equal
deleted
inserted
replaced
5080:790da8154ef8 | 5081:154becd92f40 |
---|---|
1 .. _overview: | |
2 | |
3 ===================== | |
4 Installation Overview | |
5 ===================== | |
6 | |
7 | |
8 Some overview and some details that can help understanding the options when | |
9 installing Kallithea. | |
10 | |
11 | |
12 Python Environment | |
13 ------------------ | |
14 | |
15 **Kallithea** is written entirely in Python_ and requires Python version | |
16 2.6 or higher. Python 3.x is currently not supported. | |
17 | |
18 Given a Python installation, there are different ways of providing the | |
19 environment for running Python applications. Each of them pretty much | |
20 corresponds to a ``site-packages`` directory somewhere where packages can be | |
21 installed. | |
22 | |
23 Kallithea itself can be run from source or be installed, but even when running | |
24 from source, there are some dependencies that must be installed in the Python | |
25 environment used for running Kallithea. | |
26 | |
27 - Packages *could* be installed in Python's ``site-packages`` directory ... but | |
28 that would require running pip_ as root and it would be hard to uninstall or | |
29 upgrade and is probably not a good idea unless using a package manager. | |
30 | |
31 - Packages could also be installed in ``~/.local`` ... but that is probably | |
32 only a good idea if using a dedicated user per application or instance. | |
33 | |
34 - Finally, it can be installed in a virtualenv_. That is a very lightweight | |
35 "container" where each Kallithea instance can get its own dedicated and | |
36 self-contained virtual environment. | |
37 | |
38 We recommend using virtualenv for installing Kallithea. | |
39 | |
40 | |
41 Installation Methods | |
42 -------------------- | |
43 | |
44 Kallithea must be installed on a server. Kallithea is installed in a Python | |
45 environment so it can use packages that are installed there and make itself | |
46 available for other packages. | |
47 | |
48 Two different cases will pretty much cover the options for how it can be | |
49 installed. | |
50 | |
51 - The Kallithea source repository can be cloned and used - it is kept stable and | |
52 can be used in production. The Kallithea maintainers use the development | |
53 branch in production. The advantage of installation from source and regularly | |
54 updating it is that you take advantage of the most recent improvements. Using | |
55 it directly from a DVCS also means that it is easy to track local customizations. | |
56 | |
57 Running ``setup.py develop`` in the source will use pip to install the | |
58 necessary dependencies in the Python environment and create a | |
59 ``.../site-packages/Kallithea.egg-link`` file there that points at the Kallithea | |
60 source. | |
61 | |
62 - Kallithea can also be installed from ready-made packages using a package manager. | |
63 The official released versions are available on PyPI_ and can be downloaded and | |
64 installed with all dependencies using ``pip install kallithea``. | |
65 | |
66 With this method, Kallithea is installed in the Python environment as any | |
67 other package, usually as a ``.../site-packages/Kallithea-X-py2.7.egg/`` | |
68 directory with Python files and everything else that is needed. | |
69 | |
70 (``pip install kallithea`` from a source tree will do pretty much the same | |
71 but build the Kallithea package itself locally instead of downloading it.) | |
72 | |
73 | |
74 Web Server | |
75 ---------- | |
76 | |
77 Kallithea is (primarily) a WSGI_ application that must be run from a web | |
78 server that expose WSGI as HTTP. | |
79 | |
80 - Kallithea uses the Paste_ tool for some admin tasks. Paste provides ``paste | |
81 serve`` as a convenient way to launch Python WSGI / web servers. | |
82 This method is perfect for development but *can* also be used for production. | |
83 | |
84 ``paste`` is a command line tool. Using it in production requires some way to | |
85 wrap it as a managable service. | |
86 | |
87 Paste come with its own web server but Kallithea defaults to use Waitress_. | |
88 Gunicorn_ is also an option. These web servers have different limited feature | |
89 sets. | |
90 | |
91 It is also common/mandatory to put another web server or (reverse) proxy in | |
92 front of these Python web servers. Nginx_ is a common choice. This simple | |
93 setup will thus often end up being quite complex. | |
94 | |
95 The configuration of which web server to use is in the ini file passed to | |
96 ``paste``. The entry point for the WSGI application is configured in | |
97 ``setup.py`` as ``kallithea.config.middleware:make_app``. | |
98 | |
99 - `Apache httpd`_ can serve WSGI applications directly using mod_wsgi_ and a | |
100 simple Python file with the necessary configuration. This is a good option if | |
101 Apache is an option. | |
102 | |
103 - IIS_ can also server WSGI applications directly using isapi-wsgi_. | |
104 | |
105 - UWSGI_ is also an option. | |
106 | |
107 The best option depends on what you are familiar with and the requirements for | |
108 performance and stability. Also, keep in mind that Kallithea mainly is serving | |
109 custom data generated from relatively slow Python process. Kallithea is also | |
110 often used inside organizations with a limited amount of users and thus no | |
111 continuous hammering from the internet. | |
112 | |
113 | |
114 .. _Python: http://www.python.org/ | |
115 .. _Gunicorn: http://gunicorn.org/ | |
116 .. _Waitress: http://waitress.readthedocs.org/en/latest/ | |
117 .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |
118 .. _Paste: http://pythonpaste.org/ | |
119 .. _PyPI: https://pypi.python.org/pypi | |
120 .. _Apache httpd: http://httpd.apache.org/ | |
121 .. _mod_wsgi: https://code.google.com/p/modwsgi/ | |
122 .. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi | |
123 .. _UWSGI: https://uwsgi-docs.readthedocs.org/en/latest/ | |
124 .. _nginx: http://nginx.org/en/ | |
125 .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services | |
126 .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29 | |
127 .. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface | |
128 .. _pylons: http://www.pylonsproject.org/ |