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.
+