Kallithea Setup Docs

[Mads Kiilerich]

Hi David

The Kallithea docs aim to help getting a very basic setup with the 
essentials. Something that perhaps can be used directly, but mainly 
serve as a starting point for further setup which is outside the scope 
of Kallithea. It is important to keep the configuration examples focused 
without introducing unnecessary concepts, or even worse: mixing up 
different concepts. We must assume that those who want to use advanced 
features (of uWSGI or other very configurable servers like Apache or 
Ngingx) will know how to use these or find the information elsewhere.

The uWSGI template *is* for setting up an uWSGI server. And yes, that 
uWSGI server is serving the HTTP protocol directly, not the uwsgi 
protocol. That seems like a fine setup for Kallithea, per 
https://uwsgi-docs.readthedocs.io/en/latest/HTTP.html#can-i-use-uwsgi-s-http-capabilities-in-production 
. I assume you are asking for clarification that the template is serving 
the HTTP protocol and not the uwsgi protocol?

The first lines of the generated uWSGI section mention HTTP basics and 
configure http-socket . uWSGI is mentioned in the documentation, both 
overview and setup, but only very clearly in the context of web/http 
server. That all seems quite clear to me. Mentioning the uwsgi protocol 
doesn't seem helpful when the goal is to help people focus on the 
essentials to get something working, and enumerating things that are 
outside scope is out of scope.

We do for convenience put an [uwsgi] section inside the Kallithea .ini 
where the uwsgi binary with one of the --ini-paste options can pick it 
up. The section name is mandated by uWSGI. In a bigger setup that use 
the uwsgi protocol, there will probably be several layers of servers 
with different configuration, and you will not be using the Kallithea 
.ini file.

The --ini-paste-logged option might be a bit of an odd uWSGI feature 
that doesn't scale to bigger setups. There could *perhaps* be a point in 
giving an example or hinting towards more complex setups with a separate 
uwsgi.ini file without relying heavily on the paste configuration.

I have no doubt that uWSGI can do great things, also with the uwsgi 
protocol. As far as I can see, that can be as simple and trivial as 
using "socket" instead of "http-socket". (I can not find any 
uwsgi-socket option, and manage-script-name only seems relevant when 
using mount points.) But when using uwsgi protocol you need another 
server in front that can serve it as http. That seems like a more 
complex setup, where I doubt even less that one size fits all. I'm sure 
there are many guides and documentation that can help with that. Or is 
there something particularly relevant for Kallithea setups?

It is indeed possible to "mount" several WSGI applications inside most 
HTTP/WSGI servers (or directly in paste), but that is a more complex 
(for example because manage-script-name becomes relevant). New users 
shouldn't have to read and understand that just to get started. But that 
seems unrelated to the uwsgi protocol.

We already have some (old and possibly outdated) mentioning of setups 
with apache and ngingx etc around 
https://kallithea.readthedocs.io/en/default/setup.html#proxy-setups and 
random setup files in 
https://kallithea-scm.org/repos/kallithea/files/stable/init.d . 
Something more elaborate for uWSGI with some examples and qualified 
recommendations could fit in there.

With this context in mind, can you clarify what changes you would propose?

/Mads


On 27/11/2022 19:25, David Griffin wrote:
> Hello all,
>
> I just set up Kallithea and there's one area of the docs that could 
> use clarification: emphasizing that setting up Kallithea with the 
> uwsgi template sets it up to use uwsgi as an HTTP server, and not a 
> uwsgi server. The name "uwsgi" is not particularly clear about this, 
> because the uwsgi server application can operate multiple protocols - 
> perhaps it would be better to name it as "uwsgi-http" to make it clear 
> which protocol the configuration is for.
>
> Incidentally, Kallithea appears to work great running under uwsgi as a 
> uwsgi server (with the additional configuration option of 
> manage-script-name = true, and setting uwsgi-socket instead of 
> http-socket). This might be a better option for running behind nginx / 
> lighttpd than the proxy_pass method you've got on your docs currently. 
> I can write this up if it's useful.
>
> All the best,
> - David
>
> _______________________________________________
> kallithea-general mailing list
> kallithea-general at sfconservancy.org
> https://lists.sfconservancy.org/mailman/listinfo/kallithea-general