Mercurial > kallithea

annotate docs/overview.rst @ 8607:291f04a72288

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: drop changing cwd in WSGI wrapper script It was introduced in 5a31d387f347 and has never been in the virtualenv version of the WSGI script, which "proves" it really is unnecessary.
author Mads Kiilerich <mads@kiilerich.com>
date Thu, 13 Aug 2020 15:30:09 +0200
parents 7a7273f08cfb
children 4d742b172010
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
8427
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
10 1. **Prepare environment and external dependencies.**
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
11 Kallithea needs:
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
12
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
13 * A filesystem where the Mercurial and Git repositories can be stored.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
14 * A database where meta data can be stored.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
15 * A Python environment where the Kallithea application and its dependencies
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
16 can be installed.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
17 * A web server that can host the Kallithea web application using the WSGI
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
18 API.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
19
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
20 2. **Install Kallithea software.**
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
21 This makes the ``kallithea-cli`` command line tool available.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
22
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
23 3. **Create low level configuration file.**
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
24 Use ``kallithea-cli config-create`` to create a ``.ini`` file with database
8442
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
25 connection info, mail server information, configuration for the specified
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
26 web server, etc.
8427
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
27
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
28 4. **Populate the database.**
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
29 Use ``kallithea-cli db-create`` with the ``.ini`` file to create the
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
30 database schema and insert the most basic information: the location of the
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
31 repository store and an initial local admin user.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
32
8576
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8569
diff changeset
33 5. **Prepare front-end files**
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8569
diff changeset
34 Some front-end files must be fetched or created using ``npm`` tooling so
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8569
diff changeset
35 they can be served to the client as static files.
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8569
diff changeset
36
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8569
diff changeset
37 6. **Configure the web server.**
8427
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
38 The web server must invoke the WSGI entrypoint for the Kallithea software
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
39 using the ``.ini`` file (and thus the database). This makes the web
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
40 application available so the local admin user can log in and tweak the
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
41 configuration further.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
42
8576
a63ccbc632d1 docs: add more section headings to setup description to show how it corresponds to the overview
Mads Kiilerich <mads@kiilerich.com>
parents: 8569
diff changeset
43 7. **Configure users.**
8427
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
44 The initial admin user can create additional local users, or configure how
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
45 users can be created and authenticated from other user directories.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
46
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
47 See the subsequent sections, the separate OS-specific instructions, and
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
48 :ref:`setup` for details on these steps.
d59cb6068e55 docs: clarify the installation steps and how things fit together
Mads Kiilerich <mads@kiilerich.com>
parents: 8209
diff changeset
49
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
50
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
51 Python environment
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
52 ------------------
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
53
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
54 **Kallithea** is written entirely in Python_ and requires Python version
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 8193
diff changeset
55 3.6 or higher.
5081
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 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
58 environment for running Python applications. Each of them pretty much
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
59 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
60 installed.
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 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
63 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
64 environment used for running 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 - 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
67 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
68 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
69
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
70 - 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
71 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
72
8193
89e9aef9b983 py3: use "python3 -m venv" instead of virtualenv package
Mads Kiilerich <mads@kiilerich.com>
parents: 7708
diff changeset
73 - Finally, it can be installed in a virtualenv. That is a very lightweight
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
74 "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
75 self-contained virtual environment.
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 We recommend using virtualenv for installing Kallithea.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
78
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
79
7653
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
80 Locale environment
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
81 ------------------
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
82
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
83 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
84 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
85 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
86
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
87 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
88 ``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
89 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
90 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
91
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
92 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
93 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
94 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
95 ``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
96 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
97 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
98 ``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
99
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
100 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
101 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
102 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
103 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
104 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
105 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
106 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
107 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
108 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
109 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
110 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
111 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
112 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
113
9bae11163c31 docs: outline the challenges of specifying a locale for services (Issue #340)
Mads Kiilerich <mads@kiilerich.com>
parents: 7456
diff changeset
114
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
115 Installation methods
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
116 --------------------
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 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
119 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
120 available for other packages.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
121
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
122 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
123 installed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
124
5435
60e04a21bf0f docs: more consistent use of --
Mads Kiilerich <madski@unity3d.com>
parents: 5433
diff changeset
125 - 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
126 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
127 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
128 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
129 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
130
5755
250f8150c4bb docs: suggest using pip instead of setup.py develop
Andrew Shadura <andrew@shadura.me>
parents: 5435
diff changeset
131 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
132 necessary dependencies in the Python environment and create a
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
133 ``.../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
134 source.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
135
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
136 - 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
137 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
138 installed with all dependencies using ``pip install kallithea``.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
139
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
140 With this method, Kallithea is installed in the Python environment as any
8209
01aca0a4f876 py3: officially support Python 3
Mads Kiilerich <mads@kiilerich.com>
parents: 8193
diff changeset
141 other package, usually as a ``.../site-packages/Kallithea-X-py3.8.egg/``
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
142 directory with Python files and everything else that is needed.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
143
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
144 (``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
145 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
146
7456
39f81c536ad4 docs: Fix a couple of build warnings
Mads Kiilerich <mads@kiilerich.com>
parents: 7437
diff changeset
147 .. note::
8444
850f096505ac docs: mention the npm dependency more clearly (Issue #345)
Mads Kiilerich <mads@kiilerich.com>
parents: 8442
diff changeset
148 Kallithea includes front-end code that needs to be processed to prepare
850f096505ac docs: mention the npm dependency more clearly (Issue #345)
Mads Kiilerich <mads@kiilerich.com>
parents: 8442
diff changeset
149 static files that can be served at run time and used on the client side. The
850f096505ac docs: mention the npm dependency more clearly (Issue #345)
Mads Kiilerich <mads@kiilerich.com>
parents: 8442
diff changeset
150 tool npm_ is used to download external dependencies and orchestrate the
850f096505ac docs: mention the npm dependency more clearly (Issue #345)
Mads Kiilerich <mads@kiilerich.com>
parents: 8442
diff changeset
151 processing. The ``npm`` binary must thus be available at install time but is
850f096505ac docs: mention the npm dependency more clearly (Issue #345)
Mads Kiilerich <mads@kiilerich.com>
parents: 8442
diff changeset
152 not used at run time.
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
153
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
154
5413
22a3fa3c4254 docs: cleanup of casing, markup and spacing of headings
Mads Kiilerich <madski@unity3d.com>
parents: 5081
diff changeset
155 Web server
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
156 ----------
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 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
159 server that serves WSGI applications over HTTP.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
160
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
161 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
162 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
163 (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
164 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
165 to use web server authentication.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
166
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
167 There are several web server options:
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
168
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 - 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
170 ``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
171 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
172 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
173 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
174
8442
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
175 Gearbox comes with its own built-in web server for development but Kallithea
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
176 defaults to using Waitress_. Gunicorn_ and Gevent_ are also options. These
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
177 web servers have different limited feature sets.
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
178
8442
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
179 The web server used by ``gearbox serve`` is configured in the ``.ini`` file.
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
180 Create it with ``config-create`` using for example ``http_server=waitress``
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
181 to get a configuration starting point for your choice of web server.
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
182
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
183 (Gearbox will do like ``paste`` and use the WSGI application entry point
8569
87de82eb7cb0 docs: update docs changes from stable 75b1994e4959 with kallithea.config.application refactoring in default 3a02b678b5e7
Mads Kiilerich <mads@kiilerich.com>
parents: 8568
diff changeset
184 ``kallithea.config.application:make_app`` as specified in ``setup.py``.)
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
185
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
186 - `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
187 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
188 Apache is an option.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
189
8442
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
190 - uWSGI_ is also a full web server with built-in WSGI module. Use
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
191 ``config-create`` with ``http_server=uwsgi`` to get a ``.ini`` file with
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
192 uWSGI configuration.
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
193
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
194 - IIS_ can also server WSGI applications directly using isapi-wsgi_.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
195
5418
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
196 - 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
197 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
198 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
199 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
200 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
201 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
202 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
203 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
204
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
205 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
206 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
207 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
208 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
209 continuous hammering from the internet.
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
210
8445
0bca9e828db2 docs: mention the need for worker process restarts to avoid "memory leaks" (Issue #346)
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
211 .. note::
0bca9e828db2 docs: mention the need for worker process restarts to avoid "memory leaks" (Issue #346)
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
212 Kallithea, the libraries it uses, and Python itself do in several places use
0bca9e828db2 docs: mention the need for worker process restarts to avoid "memory leaks" (Issue #346)
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
213 simple caching in memory. Caches and memory are not always released in a way
0bca9e828db2 docs: mention the need for worker process restarts to avoid "memory leaks" (Issue #346)
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
214 that is suitable for long-running processes. They might appear to be leaking
0bca9e828db2 docs: mention the need for worker process restarts to avoid "memory leaks" (Issue #346)
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
215 memory. The worker processes should thus regularly be restarted - for
0bca9e828db2 docs: mention the need for worker process restarts to avoid "memory leaks" (Issue #346)
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
216 example after 1000 requests and/or one hour. This can usually be done by the
0bca9e828db2 docs: mention the need for worker process restarts to avoid "memory leaks" (Issue #346)
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
217 web server or the tool used for running it as a system service.
0bca9e828db2 docs: mention the need for worker process restarts to avoid "memory leaks" (Issue #346)
Mads Kiilerich <mads@kiilerich.com>
parents: 8444
diff changeset
218
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
219
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
220 .. _Python: http://www.python.org/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
221 .. _Gunicorn: http://gunicorn.org/
8442
75b1994e4959 docs: make it more clear that config-create with http_server=X should be used (Issue #358)
Mads Kiilerich <mads@kiilerich.com>
parents: 8427
diff changeset
222 .. _Gevent: http://www.gevent.org/
8604
61bd04b90f58 docs: clean up readthedocs URLs
Mads Kiilerich <mads@kiilerich.com>
parents: 8576
diff changeset
223 .. _Waitress: https://docs.pylonsproject.org/projects/waitress/
61bd04b90f58 docs: clean up readthedocs URLs
Mads Kiilerich <mads@kiilerich.com>
parents: 8576
diff changeset
224 .. _Gearbox: https://turbogears.readthedocs.io/en/latest/turbogears/gearbox.html
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
225 .. _PyPI: https://pypi.python.org/pypi
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
226 .. _Apache httpd: http://httpd.apache.org/
8605
7a7273f08cfb docs: mod_wsgi is no longer on google code
Mads Kiilerich <mads@kiilerich.com>
parents: 8604
diff changeset
227 .. _mod_wsgi: https://modwsgi.readthedocs.io/
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
228 .. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi
8604
61bd04b90f58 docs: clean up readthedocs URLs
Mads Kiilerich <mads@kiilerich.com>
parents: 8576
diff changeset
229 .. _uWSGI: https://uwsgi-docs.readthedocs.io/
5081
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
230 .. _nginx: http://nginx.org/en/
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
231 .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
232 .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29
154becd92f40 docs: add installation overview section
Mads Kiilerich <madski@unity3d.com>
parents:
diff changeset
233 .. _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
234 .. _HAProxy: http://www.haproxy.org/
439792d55052 docs: try to improve the web server overview page
Mads Kiilerich <madski@unity3d.com>
parents: 5417
diff changeset
235 .. _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
236 .. _npm: https://www.npmjs.com/