diff --git a/docs/setup/deploying/apache.rst b/docs/setup/deploying/apache.rst new file mode 100644 index 0000000..eba8af7 --- /dev/null +++ b/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 + + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + Require all granted + + +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/ diff --git a/docs/setup/deploying/index.rst b/docs/setup/deploying/index.rst new file mode 100644 index 0000000..9ae7ddc --- /dev/null +++ b/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 diff --git a/docs/setup/deploying/wsgi-standalone.rst b/docs/setup/deploying/wsgi-standalone.rst new file mode 100644 index 0000000..d7fab3d --- /dev/null +++ b/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/