annotate docs/overview.rst @ 7044:eaf600434cf5

less: change markup and styling for the logo shown in the top left corner Based on work by Dominik Ruf, but in this changeset, the goal is just to improve markup and styling while keeping exactly the same look and feel. In that process, it also fixes some browser specific issues that gave odd spacing/positioning. All styling (especially the logo image URL) is moved to CSS/LESS, using background-image styling instead of an img tag. The logo image is made a :before on the site branding text and will usually have to align with this text, so we use inline-block to align to the baseline. We set the right amount of negative margin-bottom so the image can go below the baseline. We use a "big enough" negative margin-top to allow the image to bleed outside the line height and into the 12px top padding. We assume the background image doesn't need cropping or panning and do thus not set background-size, background-position, or background-repeat.
author Mads Kiilerich <mads@kiilerich.com>
date Mon, 27 Nov 2017 02:55:44 +0100
parents 2c3d30095d5e
children 6ef837acb0d2
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
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6339
diff changeset
87 - Kallithea uses the Gearbox_ tool as command line interface. Gearbox provides
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6339
diff changeset
88 ``gearbox serve`` as a convenient way to launch a Python WSGI / web server
5418
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
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6339
diff changeset
93 Gearbox comes with its own built-in web server but Kallithea defaults to use
5418
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
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6339
diff changeset
97 The web server used by ``gearbox`` is configured in the ``.ini`` file passed
5418
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
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6339
diff changeset
116 of a ``gearbox serve`` 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
6554
2c3d30095d5e gearbox: replace paster with something TurboGears2-ish that still works with the Pylons stack
Mads Kiilerich <madski@unity3d.com>
parents: 6339
diff changeset
129 .. _Gearbox: http://turbogears.readthedocs.io/en/latest/turbogears/gearbox.html
5081
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
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
139 .. _HAProxy: http://www.haproxy.org/
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
140 .. _Varnish: https://www.varnish-cache.org/