Mercurial > kallithea

annotate docs/overview.rst @ 5374:d69aa464f373

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cleanup: consistently use 'except ... as ...:' Use the Python 2.6+ syntax instead of the old confusing 'except ..., ...' syntax.
author Mads Kiilerich <madski@unity3d.com>
date Sun, 09 Aug 2015 02:17:14 +0200
parents 154becd92f40
children 22a3fa3c4254
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 =====================
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
4 Installation Overview
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
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
8 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
9 installing Kallithea.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
10
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
11
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
12 Python Environment
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
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
15 **Kallithea** is written entirely in Python_ and requires Python version
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
16 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
17
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
18 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
19 environment for running Python applications. Each of them pretty much
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
20 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
21 installed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
22
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
23 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
24 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
25 environment used for running Kallithea.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
26
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
27 - 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
28 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
29 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
30
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
31 - 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
32 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
33
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
34 - 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
35 "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
36 self-contained virtual environment.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
37
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
38 We recommend using virtualenv for installing Kallithea.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
39
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
40
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
41 Installation Methods
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
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
44 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
45 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
46 available for other packages.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
47
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
48 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
49 installed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
50
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
51 - The Kallithea source repository can be cloned and used - it is kept stable and
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
52 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
53 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
54 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
55 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
56
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
57 Running ``setup.py develop`` in the source will use pip to install the
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
58 necessary dependencies in the Python environment and create a
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
59 ``.../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
60 source.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
61
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
62 - 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
63 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
64 installed with all dependencies using ``pip install kallithea``.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
65
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
66 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
67 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
68 directory with Python files and everything else that is needed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
69
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
70 (``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
71 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
72
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
73
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
74 Web Server
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
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
77 Kallithea is (primarily) a WSGI_ application that must be run from a web
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
78 server that expose WSGI as HTTP.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
79
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
80 - Kallithea uses the Paste_ tool for some admin tasks. Paste provides ``paste
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
81 serve`` as a convenient way to launch Python WSGI / web servers.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
82 This method is perfect for development but *can* also be used for production.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
83
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
84 ``paste`` is a command line tool. Using it in production requires some way to
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
85 wrap it as a managable service.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
86
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
87 Paste come with its own web server but Kallithea defaults to use Waitress_.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
88 Gunicorn_ is also an option. These web servers have different limited feature
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
89 sets.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
90
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
91 It is also common/mandatory to put another web server or (reverse) proxy in
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
92 front of these Python web servers. Nginx_ is a common choice. This simple
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
93 setup will thus often end up being quite complex.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
94
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
95 The configuration of which web server to use is in the ini file passed to
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
96 ``paste``. The entry point for the WSGI application is configured in
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
97 ``setup.py`` as ``kallithea.config.middleware:make_app``.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
98
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
99 - `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
100 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
101 Apache is an option.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
102
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
103 - IIS_ can also server WSGI applications directly using isapi-wsgi_.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
104
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
105 - UWSGI_ is also an option.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
106
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
107 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
108 performance and stability. Also, keep in mind that Kallithea mainly is serving
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
109 custom data generated from relatively slow Python process. Kallithea is also
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
110 often used inside organizations with a limited amount of users and thus no
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
111 continuous hammering from the internet.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
112
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
113
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
114 .. _Python: http://www.python.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
115 .. _Gunicorn: http://gunicorn.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
116 .. _Waitress: http://waitress.readthedocs.org/en/latest/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
117 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
118 .. _Paste: http://pythonpaste.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
119 .. _PyPI: https://pypi.python.org/pypi
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
120 .. _Apache httpd: http://httpd.apache.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
121 .. _mod_wsgi: https://code.google.com/p/modwsgi/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
122 .. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
123 .. _UWSGI: https://uwsgi-docs.readthedocs.org/en/latest/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
124 .. _nginx: http://nginx.org/en/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
125 .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
126 .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
127 .. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
128 .. _pylons: http://www.pylonsproject.org/