Some deployment docs

docs/setup/deploying/apache.rst

@@ -0,0 +1,54 @@
+Apache and mod_wsgi
+===================
+
+If you are using the `Apache`__ webserver, you can use it to run Supysonic with
+the help of `mod_wsgi`__.
+
+__ https://httpd.apache.org/
+__ https://github.com/GrahamDumpleton/mod_wsgi
+
+Installing `mod_wsgi`
+---------------------
+
+If you don't have `mod_wsgi` installed yet you have to install it and enable it
+first as follows::
+
+   # apt install libapache2-mod-wsgi-py3
+   # a2enmod wsgi
+
+Creating a `.wsgi` file
+-----------------------
+
+To run Supysonic within Apache you need a :file:`supysonic.wsgi` file. Create
+one somewhere and fill it with the following content::
+
+   from supysonic.web import create_application
+   application = create_application()
+
+Store that file somewhere that you will find it again (e.g.:
+:file:`/var/www/supysonic/supysonic.wsgi`).
+
+Configuring Apache
+------------------
+
+The last thing you have to do is to edit the Apache configuration to tell it to
+load the application. Here's a basic example of what it looks like:
+
+.. code-block:: apache
+
+   WSGIScriptAlias /supysonic /var/www/supysonic/supysonic.wsgi
+   <Directory /var/www/supysonic>
+      WSGIApplicationGroup %{GLOBAL}
+      WSGIPassAuthorization On
+      Require all granted
+   </Directory>
+
+With that kind of configuration, the server address will look like
+`http://server/supysonic/`.
+
+For more information consult the `mod_wsgi documentation`__. Note that the
+``WSGIPassAuthorization`` directive is required for some clients as they provide
+their credentials using the *basic access authentification* mechanism rather
+than as URL query parameters.
+
+__ https://modwsgi.readthedocs.io/en/latest/

docs/setup/deploying/index.rst

@@ -0,0 +1,19 @@
+Running the web server
+======================
+
+Once Supysonic is installed and configured, you'll have to start its web server
+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
+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

docs/setup/deploying/wsgi-standalone.rst

@@ -0,0 +1,61 @@
+Standalone WSGI Containers
+==========================
+
+There are popular servers written in Python that contain WSGI applications and
+serve HTTP. These servers stand alone when they run; you can let your clients
+access them directly or proxy to them from your web server such as Apache
+or nginx.
+
+Gunicorn
+--------
+
+`Gunicorn`__ "Green Unicorn" is a WSGI HTTP Server for UNIX. It's a pre-fork
+worker model. Running Supysonic on this server is quite simple. First install
+Gunicorn with either :command:`pip install gunicorn` or
+:command:`apt install gunicorn3` (the ``gunicorn`` package in this case is
+for Python 2 which isn't supported anymore). Then::
+
+   $ gunicorn "supysonic.web:create_application()"
+
+But this will only listen on the loopback interface, which isn't really useful.
+
+Gunicorn provides many command-line options -- see :command:`gunicorn -h`.
+For example, to run Supysonic with 4 worker processes (``-w 4``) binding to all
+IPv4 interfaces on port 5000 (``-b 0.0.0.0:5000``)::
+
+   $ gunicorn -w 4 -b 0.0.0.0:5000 "supysonic.web:create_application()"
+
+__ https://gunicorn.org/
+
+uWSGI
+-----
+
+`uWSGI`__ is a fast application server written in C. It is very configurable
+which makes it more complicated to setup than gunicorn.
+
+To use it, install the package ``uwsgi`` with either :command:`pip` or
+:command:`apt`. Using the later, wou might also need the additional package
+``uwsgi-plugin-python3``.
+
+Then to run Supysonic in uWSGI::
+
+   $ uwsgi --http-socket 0.0.0.0:5000 --module "supysonic.web:create_application()"
+
+If it complains about an unknown ``--module`` option, try adding
+``--plugin python3``::
+
+   $ uwsgi --http-socket 0.0.0.0:5000 --plugin python3 --module "supysonic.web:create_application()"
+
+As uWSGI is highly configurable there are several options you could use to tweak
+it to your liking. Detailing all it can do is way beyond the scope of this
+documentation, if you're interested please refer to its documentation.
+
+If you plan on using uWSGI behind a nginx reverse proxy, note that nginx
+provides options to integrate directly with uWSGI. You'll find an example
+configuration in `Flask's documentation`__ (the framework Supysonic is built
+upon). Replace the ``myapp:app`` in their example by
+``supysonic.web:create_application()`` (you might need to enclose it in
+double-quotes).
+
+__ https://uwsgi-docs.readthedocs.io/en/latest/
+__ https://flask.palletsprojects.com/en/1.1.x/deploying/uwsgi/