Mercurial > kallithea

annotate docs/overview.rst @ 7673:642847355a10

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
hooks: make sure push and pull hooks always are enabled Don't put things in the database when we pretty much assume they always have exact content, without any reasonable use case for customization.
author Mads Kiilerich <mads@kiilerich.com>
date Wed, 23 Jan 2019 03:52:13 +0100
parents 9bae11163c31
children ab30729c735c
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
7653
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
40 Locale environment
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
41 ------------------
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
42
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
43 In order to ensure a correct functioning of Kallithea with respect to non-ASCII
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
44 characters in user names, file paths, commit messages, etc., it is very
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
45 important that Kallithea is run with a correct `locale` configuration.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
46
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
47 On Unix, environment variables like ``LANG`` or ``LC_ALL`` can specify a language (like
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
48 ``en_US``) and encoding (like ``UTF-8``) to use for code points outside the ASCII
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
49 range. The flexibility of supporting multiple encodings of Unicode has the flip
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
50 side of having to specify which encoding to use - especially for Mercurial.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
51
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
52 It depends on the OS distribution and system configuration which locales are
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
53 available. For example, some Docker containers based on Debian default to only
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
54 supporting the ``C`` language, while other Linux environments have ``en_US`` but not
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
55 ``C``. The ``locale -a`` command will show which values are available on the
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
56 current system. Regardless of the actual language, you should normally choose a
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
57 locale that has the ``UTF-8`` encoding (note that spellings ``utf8``, ``utf-8``,
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
58 ``UTF8``, ``UTF-8`` are all referring to the same thing)
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
59
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
60 For technical reasons, the locale configuration **must** be provided in the
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
61 environment in which Kallithea runs - it cannot be specified in the ``.ini`` file.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
62 How to practically do this depends on the web server that is used and the way it
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
63 is started. For example, gearbox is often started by a normal user, either
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
64 manually or via a script. In this case, the required locale environment
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
65 variables can be provided directly in that user's environment or in the script.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
66 However, web servers like Apache are often started at boot via an init script or
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
67 service file. Modifying the environment for this case would thus require
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
68 root/administrator privileges. Moreover, that environment would dictate the
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
69 settings for all web services running under that web server, Kallithea being
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
70 just one of them. Specifically in the case of Apache with ``mod_wsgi``, the
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
71 locale can be set for a specific service in its ``WSGIDaemonProcess`` directive,
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
72 using the ``lang`` parameter.
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
73
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
74
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
75 Installation methods
5081
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
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
78 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
79 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
80 available for other packages.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
81
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
82 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
83 installed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
84
5435
60e04a21bf0f docs: more consistent use of --
Mads Kiilerich <madski@unity3d.com>
parents: 5433
diff changeset
85 - 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
86 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
87 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
88 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
89 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
90
5755
250f8150c4bb docs: suggest using pip instead of setup.py develop
Andrew Shadura <andrew@shadura.me>
parents: 5435
diff changeset
91 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
92 necessary dependencies in the Python environment and create a
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
93 ``.../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
94 source.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
95
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
96 - 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
97 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
98 installed with all dependencies using ``pip install kallithea``.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
99
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
100 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
101 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
102 directory with Python files and everything else that is needed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
103
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
104 (``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
105 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
106
7456
39f81c536ad4 docs: Fix a couple of build warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 7437
diff changeset
107 .. note::
39f81c536ad4 docs: Fix a couple of build warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 7437
diff changeset
108 Kallithea includes front-end code that needs to be processed first.
39f81c536ad4 docs: Fix a couple of build warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 7437
diff changeset
109 The tool npm_ is used to download external dependencies and orchestrate the
39f81c536ad4 docs: Fix a couple of build warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 7437
diff changeset
110 processing. The ``npm`` binary must thus be available.
7055
6ef837acb0d2 less: don't distribute the generated style.css file - for now, it must be built with npm after installing Kallithea
domruf <dominikruf@gmail.com>
parents: 6554
diff changeset
111
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
112
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
113 Web server
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
114 ----------
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
115
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
116 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
117 server that serves WSGI applications over HTTP.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
118
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
119 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
120 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
121 (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
122 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
123 to use web server authentication.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
124
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
125 There are several web server options:
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
126
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
127 - 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
128 ``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
129 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
130 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
131 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
132
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
133 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
134 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
135 limited feature sets.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
136
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
137 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
138 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
139 in ``setup.py`` as ``kallithea.config.middleware:make_app``.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
140
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
141 - `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
142 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
143 Apache is an option.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
144
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
145 - 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
146
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
147 - IIS_ can also server WSGI applications directly using isapi-wsgi_.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
148
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
149 - 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
150 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
151 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
152 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
153 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
154 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
155 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
156 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
157
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
158 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
159 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
160 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
161 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
162 continuous hammering from the internet.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
163
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
164
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
165 .. _Python: http://www.python.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
166 .. _Gunicorn: http://gunicorn.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
167 .. _Waitress: http://waitress.readthedocs.org/en/latest/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
168 .. _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
169 .. _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
170 .. _PyPI: https://pypi.python.org/pypi
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
171 .. _Apache httpd: http://httpd.apache.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
172 .. _mod_wsgi: https://code.google.com/p/modwsgi/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
173 .. _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
174 .. _uWSGI: https://uwsgi-docs.readthedocs.org/en/latest/
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
175 .. _nginx: http://nginx.org/en/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
176 .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
177 .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
178 .. _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
179 .. _HAProxy: http://www.haproxy.org/
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
180 .. _Varnish: https://www.varnish-cache.org/
7437
b66725ba01ed cli: add command 'kallithea-cli front-end-build'
Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
parents: 7055
diff changeset
181 .. _npm: https://www.npmjs.com/