From 26a0b7a712296c715845043b460bab160736806d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 23 Jan 2021 18:33:25 +0100 Subject: [PATCH] Simplfy the README --- README.md | 248 ++++++++----------------------------------------- docs/index.rst | 2 +- 2 files changed, 39 insertions(+), 211 deletions(-) diff --git a/README.md b/README.md index 1d4fac7..008a1eb 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Supysonic -_Supysonic_ is a Python implementation of the [Subsonic][] server API. +Supysonic is a Python implementation of the [Subsonic][] server API. ![Build Status](https://github.com/spl0k/supysonic/workflows/Tests/badge.svg) [![codecov](https://codecov.io/gh/spl0k/supysonic/branch/master/graph/badge.svg)](https://codecov.io/gh/spl0k/supysonic) @@ -9,198 +9,53 @@ _Supysonic_ is a Python implementation of the [Subsonic][] server API. Current supported features are: * browsing (by folders or tags) * streaming of various audio file formats -* [transcoding] +* transcoding * user or random playlists -* cover arts (as image files in the same folder as music files) +* cover art * starred tracks/albums and ratings * [Last.FM][lastfm] scrobbling * Jukebox mode -_Supysonic_ currently targets the version 1.10.2 of the _Subsonic_ API. For more +Supysonic currently targets the version 1.10.2 of the Subsonic API. For more details, go check the [API implementation status][docs-api]. [subsonic]: http://www.subsonic.org/ -[transcoding]: docs/transcoding.rst -[lastfm]: https://last.fm/ -[docs-api]: docs/api.rst +[lastfm]: https://www.last.fm/ +[docs-api]: https://supysonic.readthedocs.io/en/latest/api.html -## Table of contents +## Documentation -* [Installation](#installation) - + [Prerequisites](#prerequisites) - + [Database initialization](#database-initialization) - + [Configuration](#configuration) -* [Running the application](#running-the-application) - + [As a standalone debug server](#as-a-standalone-debug-server) - + [As an Apache WSGI application](#as-an-apache-wsgi-application) - + [Other options](#other-options) - + [Docker](#docker) -* [Quickstart](#quickstart) -* [Running the daemon](#running-the-daemon) -* [Upgrading](#upgrading) - -## Installation - -_Supysonic_ can run as a standalone application (not recommended for a -"production" server) or as a WSGI application (on _Apache_ for instance). - -To install it, either run: - - $ python setup.py install - -or - - $ pip install . - -but not both. - -### Prerequisites - -You'll need Python 3.5 or later to run _Supysonic_. - -All the dependencies will automatically be installed by the installation -command above. - -You may also need a database specific package if you don't want to use SQLite -(the default): - -* _MySQL_: `pip install pymysql` or `pip install mysqlclient` -* _PostgreSQL_: `pip install psycopg2-binary` - -### Database initialization - -_Supysonic_ needs a database to run. It can either be a _SQLite_, -_MySQL_-compatible or _PostgreSQL_ database. - -Please refer to the documentation of the DBMS you've chosen on how to create a -database. Once it has a database, _Supysonic_ will automatically create the -tables it needs. - -If you want to use _PostgreSQL_ you'll have to add the `citext` extension to the -database once created. This can be done when connected to the database as the -superuser with the folowing SQL command: - - supysonic=# CREATE EXTENSION citext; - -If you absolutely have no clue about databases, you can go with _SQLite_ as it -doesn't need any setup other than specifying a path for the database. -Note that using _SQLite_ for large libraries might not be the brightest idea as -it tends to struggle with larger datasets. - -### Configuration - -Once you have a database, you'll need to create a configuration file. It must -be saved under one of the following paths: - -* `/etc/supysonic` -* `~/.supysonic` -* `~/.config/supysonic/supysonic.conf` - -A roughly documented sample configuration file is provided as `config.sample`. - -The minimal configuration using a _SQLite_ database would be: - -```ini -[base] -database_uri = sqlite:////some/path/to/a/supysonic.db -``` - -For a more details on the configuration, please refer to -[documentation][docs-config]. - -[docs-config]: docs/setup/configuration.rst - -## Running the application - -### As a standalone debug server - -It is possible to run _Supysonic_ as a standalone server, but it is only -recommended to do so if you are hacking on the source. A standalone won't be -able to serve more than one request at a time. - -To start the server, just run the `cgi-bin/server.py` script. - - $ python cgi-bin/server.py - -By default, it will listen on the loopback interface (`127.0.0.1`) on port -5000, but you can specify another address on the command line, for instance on -all the IPv6 interfaces: - - $ python cgi-bin/server.py :: - -### As an _Apache_ WSGI application - -_Supysonic_ can run as a WSGI application with the `cgi-bin/supysonic.wsgi` -file. To run it within an _Apache2_ server, first you need to install the WSGI -module and enable it. - - $ apt install libapache2-mod-wsgi-py3 - $ a2enmod wsgi - -Next, edit the _Apache_ configuration to load the application. Here's a basic -example of what it looks like: - - WSGIScriptAlias /supysonic /path/to/supysonic/cgi-bin/supysonic.wsgi - - WSGIApplicationGroup %{GLOBAL} - WSGIPassAuthorization On - Require all granted - - -With that kind of configuration, the server address will look like -*http://server/supysonic/* - -### Other options - -If you use another HTTP server, such as _nginx_ or _lighttpd_, or prefer to use -FastCGI or CGI over WSGI, FastCGI and CGI scripts are also provided in the -`cgi-bin` folder, respectively as `supysonic.fcgi` and `supysonic.cgi`. You -might need to edit those file to suit your system configuration. - -Here are some quick docs on how to configure your server for [FastCGI][] or -[CGI][]. - -[fastcgi]: http://flask.pocoo.org/docs/deploying/fastcgi/ -[cgi]: http://flask.pocoo.org/docs/deploying/cgi/ - -### Docker - -If you want to run _Supysonic_ in a _Docker_ container, here are some images -provided by the community. - -- https://github.com/ultimate-pms/docker-supysonic -- https://github.com/ogarcia/docker-supysonic -- https://github.com/foosinn/supysonic -- https://github.com/mikafouenski/docker-supysonic -- https://github.com/oakman/supysonic-docker -- https://github.com/glogiotatidis/supysonic-docker +Full documentation is available at https://supysonic.readthedocs.io/ ## Quickstart -To start using _Supysonic_, you'll first have to specify where your music -library is located and create a user to allow calls to the API. - -Let's start by creating a new admin user this way: - - $ supysonic-cli user add MyUserName -p MyAwesomePassword - $ supysonic-cli user setroles -A MyUserName - -To add a new folder to your music library, you can do something like this: +Use the following commands to install Supysonic, create an admin user, define a +library folder, scan it and start serving using [Gunicorn][]. + $ pip install git+https://github.com/spl0k/supysonic.git + $ pip install gunicorn + $ supysonic-cli user add MyUserName + $ supysonic-cli user setroles --admin MyUserName $ supysonic-cli folder add MyLibrary /home/username/Music - -Once you've added a folder, you will need to scan it: - $ supysonic-cli folder scan MyLibrary + $ gunicorn -b 0.0.0.0:5000 "supysonic.web:create_application()" You should now be able to enjoy your music with the client of your choice! -For more details on the command-line usage, take a look at the -[documentation][docs-cli]. +But using only the above commands will use a default configuration and +especially storing the database in a temporary directory. Head over to the +documentaiton for [full setup instructions][docs-setup], plus other options if +you don't want to use Gunicorn. -[docs-cli]: docs/man/supysonic-cli.rst +Note that there's also an optional [daemon][docs-daemon] that watches for +library changes and provides support for other features such as the +jukebox mode. -## Client authentication +[gunicorn]: https://gunicorn.org/ +[docs-setup]: https://supysonic.readthedocs.io/en/latest/setup/index.html +[docs-daemon]: https://supysonic.readthedocs.io/en/latest/setup/daemon.html + +## About client authentication The Subsonic API provides several authentication methods. One of them, known as _token authentication_ was added with API version 1.13.0. As Supysonic currently @@ -208,46 +63,19 @@ targets API version 1.9.0, the token based method isn't supported. So if your client offers you the option, you'll have to disable the token based authentication for it to work. -## Running the daemon +## Development stuff -_Supysonic_ comes with an optional daemon service that currently provides the -following features: -- background scans -- library changes detection -- jukebox mode +For those wishing to collaborate on the project, since Supysonic uses [Flask][] +you can use its development server which provides automatic reloading and +in-browser debugging among other things. To start said server: -First of all, the daemon allows running backgrounds scans, meaning you can start -scans from the CLI and do something else while it's scanning (otherwise the scan -will block the CLI until it's done). -Background scans also enable the web UI to run scans, while you have to use the -CLI to do so if you don't run the daemon. + $ export FLASK_APP="supysonic.web:create_application()" + $ export FLASK_ENV=development + $ flask run -Instead of manually running a scan every time your library changes, the daemon -can listen to any library change and update the database accordingly. This -watcher is started along with the daemon but can be disabled to only keep -background scans. +And there's also the tests: -Finally, the daemon acts as a backend for the jukebox mode, allowing to play -audio on the machine running Supysonic. + $ python setup.py test + $ python setup.py test --test-suite tests.with_net -The daemon is `supysonic-daemon`, it is a non-exiting process. If you want to -keep it running in background, either use the old `nohup` or `screen` methods, -or start it as a _systemd_ unit (see the very basic _supysonic-daemon.service_ -file). - -## Upgrading - -To upgrade your _Supysonic_ installation, simply re-run the command you used to -install it (either `python setup.py install` or `pip install .`). - -Some commits might introduce changes in the database schema. Starting with -commit e84459d6278bfc735293edc19b535c62bc2ccd8d (August 29th, 2018) migrations -will be automatically applied. - -If your database was created prior to this date, you'll have to manually apply -unapplied migrations up to the latest. Once done you won't have to worry about -future migrations as they'll be automatically applied. -Migration scripts are provided in the `supysonic/schema/migration` folder, named -by the date of commit that introduced the schema changes. There could be both -SQL scripts or Python scripts. The Python scripts require arguments that are -explained when the script is invoked with the `-h` flag. +[flask]: https://flask.palletsprojects.com/ \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 3782e13..96c540e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,7 @@ Current supported features are: * streaming of various audio file formats * transcoding * user or random playlists -* cover arts (as image files in the same folder as music files) +* cover art * starred tracks/albums and ratings * `Last.FM`__ scrobbling * Jukebox mode