Mercurial > kallithea
annotate docs/overview.rst @ 7963:46681ae86693
db: introduce migration step after 93834966ae01 dropped non-nullable inherit_default_permissions
The database migration step was lazily and naively skipped ... but that turns
out to be a problem when new users are added.
In the database, the original column 'inherit_default_permissions' was
marked as non-nullable without default value. In the Kallithea code after
commit 93834966ae01, the column 'inherit_default_permissions' was no longer
known, and thus not given a value when new users are added. As a result, the
database complained:
IntegrityError: (psycopg2.errors.NotNullViolation) null value in column "inherit_default_permissions" violates not-null constraint
Fix that now by adding an appropriate db migration step to actually remove
the columns.
Use meta reflection to check if columns exist before running the upgrade
step. The upgrade step only has to be run if it is an old database - not if
it has been created after the schema changes were introduced.
For the downgrade step, make sure to set a default value for non-nullable
columns.
author | Mads Kiilerich <mads@kiilerich.com> |
---|---|
date | Sat, 23 Nov 2019 02:27:19 +0100 |
parents | ab30729c735c |
children | 89e9aef9b983 |
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 |
7708
ab30729c735c
setup: drop support for Python 2.6
Mads Kiilerich <mads@kiilerich.com>
parents:
7653
diff
changeset
|
15 2.7 or higher. Python 3.x is currently not supported. |
5081
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/ |