From a033d45605fc28cfc5839108c96694d9cb60add7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 6 Nov 2021 17:51:54 +0100 Subject: [PATCH] Adding doc for the newly added `supysonic-server` --- README.md | 4 +- docs/conf.py | 9 +++- docs/man/index.rst | 7 +++ docs/man/supysonic-cli.rst | 6 +-- docs/man/supysonic-server.rst | 68 ++++++++++++++++++++++++ docs/setup/deploying/index.rst | 24 ++++++++- docs/setup/deploying/wsgi-standalone.rst | 10 ++-- docs/setup/index.rst | 2 +- docs/setup/install.rst | 23 +++++--- supysonic/server/__init__.py | 2 + 10 files changed, 134 insertions(+), 21 deletions(-) create mode 100644 docs/man/supysonic-server.rst diff --git a/README.md b/README.md index 108e040..a0e7e60 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Full documentation is available at https://supysonic.readthedocs.io/ ## Quickstart Use the following commands to install Supysonic, create an admin user, define a -library folder, scan it and start serving using [Gunicorn][]. +library folder, scan it and start serving on port 5722 using [Gunicorn][]. $ pip install git+https://github.com/spl0k/supysonic.git $ pip install gunicorn @@ -38,7 +38,7 @@ library folder, scan it and start serving using [Gunicorn][]. $ supysonic-cli user setroles --admin MyUserName $ supysonic-cli folder add MyLibrary /home/username/Music $ supysonic-cli folder scan MyLibrary - $ gunicorn -b 0.0.0.0:5000 "supysonic.web:create_application()" + $ supysonic-server You should now be able to enjoy your music with the client of your choice! diff --git a/docs/conf.py b/docs/conf.py index 1f7e81f..36452cc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,7 +66,7 @@ man_pages = [ ( "man/supysonic-cli", "supysonic-cli", - "Python implementation of the Subsonic server API", + "Supysonic management command line interface", _man_authors, 1, ), @@ -91,4 +91,11 @@ man_pages = [ _man_authors, 1, ), + ( + "man/supysonic-server", + "supysonic-server", + "Python implementation of the Subsonic server API", + [author], + 1 + ) ] diff --git a/docs/man/index.rst b/docs/man/index.rst index a5d55bc..df1b307 100644 --- a/docs/man/index.rst +++ b/docs/man/index.rst @@ -10,6 +10,13 @@ Man pages supysonic-cli-user supysonic-cli-folder +.. rubric:: Web server + +.. toctree:: + :maxdepth: 2 + + supysonic-server + .. rubric:: Daemon .. toctree:: diff --git a/docs/man/supysonic-cli.rst b/docs/man/supysonic-cli.rst index a19de78..05313b1 100644 --- a/docs/man/supysonic-cli.rst +++ b/docs/man/supysonic-cli.rst @@ -2,9 +2,9 @@ supysonic-cli ============= ------------------------------------------------- -Python implementation of the Subsonic server API ------------------------------------------------- +------------------------------------------- +Supysonic management command line interface +------------------------------------------- :Author: Louis-Philippe Véronneau, Alban Féron :Date: 2019, 2021 diff --git a/docs/man/supysonic-server.rst b/docs/man/supysonic-server.rst new file mode 100644 index 0000000..6bf657b --- /dev/null +++ b/docs/man/supysonic-server.rst @@ -0,0 +1,68 @@ +================ +supysonic-server +================ + +------------------------------------------------ +Python implementation of the Subsonic server API +------------------------------------------------ + +:Author: Alban Féron +:Date: 2021 +:Manual section: 1 + +Synopsis +======== + +``supysonic-server`` [``--server`` ``gevent``\|\ ``gunicorn``\|\ ``waitress``] +[``--host`` `hostname`] [``--port`` `port`] [``--socket`` `path`] +[``--processes`` `n`] [``--threads`` `n`] + +Description +=========== + +``supysonic-server`` is the main Supysonic's component, allowing to serve +content to clients. It is actually a basic wrapper over ``Gevent``, ``Gunicorn`` +or ``Waitress``, requiring at least one of them to be installed to run. + +Options +======= + +-S name, --server name + Specify which WSGI server to use. `name` must be one of ``gevent``, + ``gunicorn`` or ``waitress`` and the matching package must then be installed. + If the option isn't provided, the first one available will be used. + +-h hostname, --host hostname + Hostname or IP address on which to listen. The default is ``0.0.0.0`` which + means to listen on all IPv4 interfaces on this host. + Cannot be used with ``--socket``. + +-p port, --port port + TCP port on which to listen. Default is ``5722``. + Cannot be used with ``--socket``. + +-s path, --socket path + Path of a Unix socket on which to bind to. If a path is specified, a Unix + domain socket is made instead of the usual inet domain socket. + Cannot be used with ``--host`` or ``--port``. + Not available on Windows. + +--processes n + Number of worker processes to spawn. Only applicable when using the + ``Gunicorn`` WSGI server (``--server gunicorn``). + +--threads n + The number of worker threads for handling requests. Only applicable when + using the ``Gunicorn`` or ``Waitress`` WSGI server (``--server gunicorn`` or + ``--server waitress``) + +Bugs +==== + +Bugs can be reported to your distribution's bug tracker or upstream +at https://github.com/spl0k/supysonic/issues. + +See Also +======== + +``supysonic-cli``\ (1) diff --git a/docs/setup/deploying/index.rst b/docs/setup/deploying/index.rst index 79b4502..0d96ece 100644 --- a/docs/setup/deploying/index.rst +++ b/docs/setup/deploying/index.rst @@ -6,7 +6,29 @@ 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. -You'll find some common (and less common) deployment option below: +supysonic-server +^^^^^^^^^^^^^^^^ + +But the easiest might be to use Supysonic's own server. It actually requires a +WSGI server library to run, so you'll first need to have either `Gevent`__, +`Gunicorn`__ or `Waitress`__ to be installed. Then you can start the server with +the following command:: + + supysonic-server + +And it will start to listen on all IPv4 interfaces on port 5722. + +This command allows some options, more details are given on its manpage: +:doc:`/man/supysonic-server`. + +__ https://www.gevent.org +__ https://gunicorn.org/ +__ https://docs.pylonsproject.org/projects/waitress/en/stable/index.html + +Other options +^^^^^^^^^^^^^ + +You'll find some other common (and less common) deployment option below: .. toctree:: :maxdepth: 2 diff --git a/docs/setup/deploying/wsgi-standalone.rst b/docs/setup/deploying/wsgi-standalone.rst index d7fab3d..5c05fc4 100644 --- a/docs/setup/deploying/wsgi-standalone.rst +++ b/docs/setup/deploying/wsgi-standalone.rst @@ -21,9 +21,9 @@ 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``):: +IPv4 interfaces on port 5722 (``-b 0.0.0.0:5722``):: - $ gunicorn -w 4 -b 0.0.0.0:5000 "supysonic.web:create_application()" + $ gunicorn -w 4 -b 0.0.0.0:5722 "supysonic.web:create_application()" __ https://gunicorn.org/ @@ -39,12 +39,12 @@ To use it, install the package ``uwsgi`` with either :command:`pip` or Then to run Supysonic in uWSGI:: - $ uwsgi --http-socket 0.0.0.0:5000 --module "supysonic.web:create_application()" + $ uwsgi --http-socket 0.0.0.0:5722 --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()" + $ uwsgi --http-socket 0.0.0.0:5722 --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 @@ -58,4 +58,4 @@ upon). Replace the ``myapp:app`` in their example by double-quotes). __ https://uwsgi-docs.readthedocs.io/en/latest/ -__ https://flask.palletsprojects.com/en/1.1.x/deploying/uwsgi/ +__ https://flask.palletsprojects.com/en/2.0.x/deploying/uwsgi/ diff --git a/docs/setup/index.rst b/docs/setup/index.rst index 610c25f..e2369af 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -15,7 +15,7 @@ music is located 😏). This uses `gunicorn`__, but there are pip install git+https://github.com/spl0k/supysonic.git pip install gunicorn - gunicorn -b 0.0.0.0:5000 "supysonic.web:create_application()" + supysonic-server __ https://gunicorn.org/ diff --git a/docs/setup/install.rst b/docs/setup/install.rst index 9482c9e..027588d 100644 --- a/docs/setup/install.rst +++ b/docs/setup/install.rst @@ -14,12 +14,6 @@ package repositories. Install the package ``supysonic`` using :command:`apt`:: This will install Supysonic along with the minimal dependencies it needs to run. -.. note:: - - As of January 2021, Supysonic only reached Debian's *testing* release. If - you're using the *stable* release it might not be available in the packages - yet. - If you plan on using it with a MySQL or PostgreSQL database you also need the corresponding Python package, ``python-pymysql`` for MySQL or ``python-psycopg2`` for PostgreSQL. @@ -76,8 +70,21 @@ or simply installing directly via :command:`pip`:: $ pip install git+https://github.com/spl0k/supysonic.git -This will install Supysonic along with the minimal dependencies it needs to -run. +This will install Supysonic along with the minimal dependencies it needs, but +those don't include the requirements for the web server. For this you'll need +to install either ``gevent``, ``gunicorn`` or ``waitress``. + +:: + + $ pip install gevent + +:: + + $ pip install gunicorn + +:: + + $ pip install waitress If you plan on using it with a MySQL or PostgreSQL database you also need the corresponding package, ``pymysql`` for MySQL or ``psycopg2-binary`` for diff --git a/supysonic/server/__init__.py b/supysonic/server/__init__.py index cafa3f4..4acc6b4 100644 --- a/supysonic/server/__init__.py +++ b/supysonic/server/__init__.py @@ -103,6 +103,8 @@ def find_first_available_server(): help="Number of threads used to process application logic. May not be supported by all servers", ) def main(server, host, port, socket, processes, threads): + """Starts the Supysonic web server""" + if server is None: server = find_first_available_server() if server is None: