From 3619d2c7a687814422eb419285556f55f7cd4ae8 Mon Sep 17 00:00:00 2001 From: boyska Date: Mon, 1 Mar 2021 12:38:10 +0100 Subject: [PATCH] doc: quickstart and common errors --- doc/source/index.rst | 2 + doc/source/quickstart.rst | 148 +++++++++++++++++++++++++++++++++ doc/source/troubleshooting.rst | 16 ++++ 3 files changed, 166 insertions(+) create mode 100644 doc/source/quickstart.rst create mode 100644 doc/source/troubleshooting.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index d8b275e..f94b3cd 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,11 +12,13 @@ Contents: :maxdepth: 2 about + quickstart install timegenerators audiogenerators eventfilters audiogenerators-write + troubleshooting debug api/modules diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst new file mode 100644 index 0000000..349edf7 --- /dev/null +++ b/doc/source/quickstart.rst @@ -0,0 +1,148 @@ +Quick start: install larigira on Debian buster +============================================== + +This guides have this assumptions or conventions: + * you have a Debian buster installation + - actually 99% of this should work in any distro with recent-enough python3 and systemd + - if you don't like systemd, you are free to use any other service manager; larigira integrates nicely with + systemd, but has no requirement at all + * you have a non-root main user, which we'll call ``radio`` + * all commands are meant to be run as root. Use ``sudo -i`` if you don't have root password + +Install +----------- + + +Let's start!:: + + apt-get install python3 python3-dev virtualenv mpd + virtualenv -p /usr/bin/python3 /opt/larigira/ + /opt/larigira/bin/pip3 install larigira + touch /etc/default/larigira + mkdir -p /home/radio/.mpd/ /etc/larigira/ /var/log/larigira/ + chown radio:adm /var/log/larigira/ + touch /etc/systemd/system/larigira.service + +Edit ``/etc/systemd/system/larigira.service`` and put this content:: + + [Unit] + Description=Radio Automation + After=mpd.service + + [Service] + EnvironmentFile=/etc/default/larigira + User=radio + ExecStart=/opt/larigira/bin/larigira + + [Install] + WantedBy=multi-user.target + +Now let's edit ``/etc/mpd.conf``:: + + music_directory "/home/radio/Music/" + playlist_directory "/home/radio/.mpd/playlists" + db_file "/home/radio/.mpd/tag_cache" + log_file "syslog" + pid_file "/home/radio/.mpd/pid" + state_file "/home/radio/.mpd/state" + sticker_file "/home/radio/.mpd/sticker.sql" + user "radio" + bind_to_address "/home/radio/.mpd/socket" + bind_to_address "127.0.0.1" + port "6600" + log_level "default" + replaygain "track" + replaygain_limit "yes" + volume_normalization "yes" + max_connections "30" + +Now let's edit larigira settings, editing the file ``/etc/default/larigira``:: + + MPD_HOST=/home/radio/.mpd/socket + LARIGIRA_DEBUG=false + LARIGIRA_LOG_CONFIG=/etc/larigira/logging.ini + + LARIGIRA_EVENT_FILTERS='["percentwait"]' + LARIGIRA_EF_MAXWAIT_PERC=400 + LARIGIRA_SECRET_KEY="changeme" + +Let's include logging configuration, editing ``/etc/larigira/logging.ini``:: + + [loggers] + keys=root + + [formatters] + keys=brief,ext,debug + + [handlers] + keys=syslog,own,owndebug,ownerr + + [logger_root] + handlers=syslog,own,owndebug,ownerr + level=DEBUG + + [handler_syslog] + class=handlers.SysLogHandler + level=INFO + args=('/dev/log', handlers.SysLogHandler.LOG_USER) + formatter=brief + + [handler_own] + class=handlers.WatchedFileHandler + level=INFO + args=('/var/log/larigira/larigira.log',) + formatter=ext + [handler_owndebug] + class=handlers.WatchedFileHandler + level=DEBUG + args=('/var/log/larigira/larigira.debug',) + formatter=debug + [handler_ownerr] + class=handlers.WatchedFileHandler + level=ERROR + args=('/var/log/larigira/larigira.err',) + formatter=ext + + [formatter_ext] + format=%(asctime)s|%(levelname)s[%(name)s] %(message)s + + [formatter_debug] + format=%(asctime)s|%(levelname)s[%(name)s:%(lineno)d] %(message)s + + [formatter_brief] + format=%(levelname)s:%(message)s + +For hygiene's sake, let's configure rotation for this log, editing ``/etc/logrotate.d/larigira``:: + + /var/log/larigira/*.err + /var/log/larigira/*.log { + daily + missingok + rotate 14 + compress + notifempty + copytruncate + create 600 + } + + /var/log/larigira/*.debug { + daily + rotate 2 + missingok + compress + notifempty + copytruncate + create 600 + } + + +Restart everything:: + + systemctl daemon-reload + systemctl restart mpd + systemctl restart larigira + systemctl enable larigira + systemctl enable mpd + + +Everything should work now! diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst new file mode 100644 index 0000000..34a6f01 --- /dev/null +++ b/doc/source/troubleshooting.rst @@ -0,0 +1,16 @@ +Common problems +==================== + + +I got AccessDenied in the logs +------------------------------ + +You are not using the UNIX socket to access MPD. See the configuration variable MPD_HOST. This is required by +MPD. + +I got ``mpd.base.CommandError: [50@0] {} No such song`` +------------------------------------------------------- + +There is permissions issues going on. Probably you are running larigira and mpd with two different users, and +you haven't set up a common group for them. +