Mercurial > kallithea

comparison docs/overview.rst @ 5418:439792d55052

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: try to improve the web server overview page Say more about the role of paster and reverse proxies and do not give any hints that the combination should be a magic silver bullet.
author Mads Kiilerich <madski@unity3d.com>
date Thu, 20 Aug 2015 17:29:55 +0200
parents 36a35394b3cb
children fbbe80e3322b
comparison
equal deleted inserted replaced
5417:36a35394b3cb 5418:439792d55052
75 ---------- 75 ----------
76 76
77 Kallithea is (primarily) a WSGI_ application that must be run from a web 77 Kallithea is (primarily) a WSGI_ application that must be run from a web
78 server that serves WSGI applications over HTTP. 78 server that serves WSGI applications over HTTP.
79 79
80 - Kallithea uses the Paste_ tool for some admin tasks. Paste provides ``paster 80 Kallithea itself is not serving HTTP (or HTTPS); that is the web server's
81 serve`` as a convenient way to launch Python WSGI / web servers. 81 responsibility. Kallithea does however need to know its own user facing URL
82 This method is perfect for development but *can* also be used for production. 82 (protocol, address, port and path) for each HTTP request. Kallithea will
83 usually use its own HTML/cookie based authentication but can also be configured
84 to use web server authentication.
83 85
84 ``paster`` is a command line tool. Using it in production requires some way to 86 There are several web server options:
85 wrap it as a manageable service.
86 87
87 Paste come with its own web server but Kallithea defaults to use Waitress_. 88 - Kallithea uses the Paste_ tool as command line interface. Paste provides
88 Gunicorn_ is also an option. These web servers have different limited feature 89 ``paster serve`` as a convenient way to launch a Python WSGI / web server
89 sets. 90 from the command line. That is perfect for development and evaluation.
91 Actual use in production might have different requirements and need extra
92 work to make it manageable as a scalable system service.
90 93
91 It is also common/mandatory to put another web server or (reverse) proxy in 94 Paste comes with its own built-in web server but Kallithea defaults to use
92 front of these Python web servers. Nginx_ is a common choice. This simple 95 Waitress_. Gunicorn_ is also an option. These web servers have different
93 setup will thus often end up being quite complex. 96 limited feature sets.
94 97
95 The configuration of which web server to use is in the ini file passed to 98 The web server used by ``paster`` is configured in the ``.ini`` file passed
96 ``paster``. The entry point for the WSGI application is configured in 99 to it. The entry point for the WSGI application is configured
97 ``setup.py`` as ``kallithea.config.middleware:make_app``. 100 in ``setup.py`` as ``kallithea.config.middleware:make_app``.
98 101
99 - `Apache httpd`_ can serve WSGI applications directly using mod_wsgi_ and a 102 - `Apache httpd`_ can serve WSGI applications directly using mod_wsgi_ and a
100 simple Python file with the necessary configuration. This is a good option if 103 simple Python file with the necessary configuration. This is a good option if
101 Apache is an option. 104 Apache is an option.
102 105
106 - uWSGI_ is also a full web server with built-in WSGI module.
107
103 - IIS_ can also server WSGI applications directly using isapi-wsgi_. 108 - IIS_ can also server WSGI applications directly using isapi-wsgi_.
104 109
105 - UWSGI_ is also an option. 110 - A `reverse HTTP proxy <https://en.wikipedia.org/wiki/Reverse_proxy>`_
111 can be put in front of another web server which has WSGI support.
112 Such a layered setup can be complex but might in some cases be the right
113 option, for example to standardize on one internet-facing web server, to add
114 encryption or special authentication or for other security reasons, to
115 provide caching of static files, or to provide load balancing or fail-over.
116 Nginx_, Varnish_ and HAProxy_ are often used for this purpose, often in front
117 of a ``paster`` server that somehow is wrapped as a service.
106 118
107 The best option depends on what you are familiar with and the requirements for 119 The best option depends on what you are familiar with and the requirements for
108 performance and stability. Also, keep in mind that Kallithea mainly is serving 120 performance and stability. Also, keep in mind that Kallithea mainly is serving
109 custom data generated from relatively slow Python process. Kallithea is also 121 dynamically generated pages from a relatively slow Python process. Kallithea is
110 often used inside organizations with a limited amount of users and thus no 122 also often used inside organizations with a limited amount of users and thus no
111 continuous hammering from the internet. 123 continuous hammering from the internet.
112 124
113 125
114 .. _Python: http://www.python.org/ 126 .. _Python: http://www.python.org/
115 .. _Gunicorn: http://gunicorn.org/ 127 .. _Gunicorn: http://gunicorn.org/
118 .. _Paste: http://pythonpaste.org/ 130 .. _Paste: http://pythonpaste.org/
119 .. _PyPI: https://pypi.python.org/pypi 131 .. _PyPI: https://pypi.python.org/pypi
120 .. _Apache httpd: http://httpd.apache.org/ 132 .. _Apache httpd: http://httpd.apache.org/
121 .. _mod_wsgi: https://code.google.com/p/modwsgi/ 133 .. _mod_wsgi: https://code.google.com/p/modwsgi/
122 .. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi 134 .. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi
123 .. _UWSGI: https://uwsgi-docs.readthedocs.org/en/latest/ 135 .. _uWSGI: https://uwsgi-docs.readthedocs.org/en/latest/
124 .. _nginx: http://nginx.org/en/ 136 .. _nginx: http://nginx.org/en/
125 .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services 137 .. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services
126 .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29 138 .. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29
127 .. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface 139 .. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface
128 .. _pylons: http://www.pylonsproject.org/ 140 .. _pylons: http://www.pylonsproject.org/
141 .. _HAProxy: http://www.haproxy.org/
142 .. _Varnish: https://www.varnish-cache.org/