FastCGI/CGI deployment docs

docs/setup/deploying/index.rst

@@ -6,14 +6,17 @@ for the clients to be able to access the music. Here you have several options,
 whether you want to run it as independant process(es), then possibly putting it
 behind a reverse proxy, or running it as a WSGI application within Apache.
 
-As Supysonic is a WSGI application, you have numerous deployment options
+You'll find some common (and less common) deployment option below:
-available to you. If you want to deploy it to a WSGI server not listed here,
-look up the server documentation about how to use a WSGI app with it. When
-setting one of those, you'll want to call the :func:`create_application` factory
-function from module :mod:`supysonic.web`.
 
 .. toctree::
    :maxdepth: 2
 
    wsgi-standalone
    apache
+   other
+
+As Supysonic is a WSGI application, you have numerous deployment options
+available to you. If you want to deploy it to a WSGI server not listed here,
+look up the server documentation about how to use a WSGI app with it. When
+setting one of those, you'll want to call the :func:`create_application` factory
+function from module :mod:`supysonic.web`.

docs/setup/deploying/other.rst

@@ -0,0 +1,96 @@
+Other options
+=============
+
+FastCGI
+-------
+
+FastCGI is a deployment option on servers like `nginx`__ or `lighttpd`__; see
+:doc:`wsgi-standalone` for other options.
+To use Supysonic with any of them you will need a FastCGI server first. The most
+popular one is `flup`__ which we will use for this guide. Make sure to have it
+installed (with eith :command:`pip` or :command:`apt`) to follow along.
+
+__ https://nginx.org/
+__ https://www.lighttpd.net/
+__ https://pypi.org/project/flup/
+
+Creating a `.fcgi` file
+^^^^^^^^^^^^^^^^^^^^^^^
+
+First you need to create the FastCGI server file. Let's call it
+:file:`supysonic.fcgi`::
+
+   #!/usr/bin/python3
+
+   from flup.server.fcgi import WSGIServer
+   from supysonic.web import create_application
+
+   if __name__ == '__main__':
+      app = create_application()
+      WSGIServer(app).run()
+
+This should be enough for Apache to work, however nginx and older versions of
+lighttpd need a socket to be explicitly passed to communicate with the
+FastCGI server. For that to work you need to pass the path to the socket
+to the :class:`~flup.server.fcgi.WSGIServer`::
+
+   WSGIServer(app, bindAddress='/path/to/fcgi.sock').run()
+
+The path has to be the exact same path you define in the server
+config.
+
+Save the :file:`supysonic.fcgi` file somewhere you will find it again.
+It makes sense to have that in :file:`/var/www/supysonic` or something
+similar.
+
+Make sure to set the executable bit on that file so that the servers
+can execute it::
+
+   $ chmod +x /var/www/supysonic/supysonic.fcgi
+
+Configuring the web server
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The example above is good enough for a basic Apache deployment but your
+`.fcgi` file will appear in your application URL e.g.
+``example.com/supysonic.fcgi/``. If that bothers you or you wish to load it in
+another web server, Flask's documentation details how to do it for `Apache`__,
+`lighttpd`__ or `nginx`__.
+
+__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-apache
+__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-lighttpd
+__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-nginx
+
+CGI
+---
+
+If all other deployment methods do not work, CGI will work for sure.
+CGI is supported by all major servers but usually has a sub-optimal
+performance.
+
+Creating a `.cgi` file
+^^^^^^^^^^^^^^^^^^^^^^
+
+First you need to create the CGI application file. Let's call it
+:file:`supysonic.cgi`::
+
+   #!/usr/bin/python3
+
+   from wsgiref.handlers import CGIHandler
+   from supysonic.web import create_application
+
+   app = create_application()
+   CGIHandler().run(app)
+
+Server Setup
+^^^^^^^^^^^^
+
+Usually there are two ways to configure the server.  Either just copy the
+``.cgi`` into a :file:`cgi-bin` (and use `mod_rewrite` or something similar to
+rewrite the URL) or let the server point to the file directly.
+
+In Apache for example you can put something like this into the config:
+
+.. sourcecode:: apache
+
+   ScriptAlias /supysonic /path/to/the/supysonic.cgi

docs/setup/index.rst

@@ -10,3 +10,4 @@ start serving your music.
     install
     database
     configuration
+    deploying/index

docs/setup/install.rst

@@ -7,10 +7,9 @@ Linux
 -----
 
 Currently, only Debian-based distributions might provide Supysonic in their
-package repositories. Install the package ``supysonic`` using either
+package repositories. Install the package ``supysonic`` using :command:`apt`::
-:command:`apt` or :command:`apt-get`::
 
-   $ apt-get install supysonic
+   $ apt install supysonic
 
 This will install Supysonic along with the minimal dependencies it needs to
 run.
@@ -27,11 +26,11 @@ corresponding Python package, ``python-pymysql`` for MySQL or
 
 ::
 
-   $ apt-get install python-pymysql
+   $ apt install python-pymysql
 
 ::
 
-   $ apt-get install python-psycopg2
+   $ apt install python-psycopg2
 
 For other distributions, you might consider installing from `docker`_ images or
 from `source`_.