Adding doc for the newly added supysonic-server

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!
 

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
+    )
 ]

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::

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

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)

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

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/

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/
 

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

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: