From 9859eab7170e5d73da421eefe70123769b8ccbc3 Mon Sep 17 00:00:00 2001 From: Florian Strzelecki Date: Sat, 28 Oct 2023 14:06:03 +0200 Subject: [PATCH] docs: install, manage plugins, run as service Co-authored-by: dgw Co-authored-by: James --- contrib/README.md | 23 --- contrib/sopel.cfg | 19 -- contrib/sopel.conf | 2 - contrib/sopel.service | 17 -- contrib/sopel@.service | 18 -- docs/source/faq.rst | 40 ++++ docs/source/index.rst | 10 +- .../tutorials/configuration-and-setup.rst | 4 +- docs/source/run.rst | 19 ++ docs/source/run/install.rst | 139 ++++++++++++++ docs/source/run/plugin.rst | 137 ++++++++++++++ docs/source/run/service.rst | 174 ++++++++++++++++++ 12 files changed, 517 insertions(+), 85 deletions(-) delete mode 100644 contrib/sopel.cfg delete mode 100644 contrib/sopel.conf delete mode 100644 contrib/sopel.service delete mode 100644 contrib/sopel@.service create mode 100644 docs/source/faq.rst create mode 100644 docs/source/run/install.rst create mode 100644 docs/source/run/plugin.rst create mode 100644 docs/source/run/service.rst diff --git a/contrib/README.md b/contrib/README.md index 732ca389ab..4d9f765f25 100644 --- a/contrib/README.md +++ b/contrib/README.md @@ -1,28 +1,5 @@ This folder contains contributed files for use with Sopel. -## Service configuration - -`sopel.service` and `sopel.cfg` are designed to be distributed by third parties -such as Fedora Project or Arch Linux. - -`sopel.cfg` is a default configuration file for Sopel, that assumes the OS is -new enough to have `/run` and `/usr/lib/tmpfiles.d` - -`sopel.service` is a systemd service file, and `sopel@.service` is a -multi-instance template. Both assume you are using a rather recent Sopel; that -the system has a special user named `sopel` designated for running the bot; and -that this user has access to `/run/sopel` (should be setup by `sopel.conf` in -`/usr/lib/tmpfiles.d`), `/var/log/sopel` and `/var/lib/sopel` - -Default installation paths: - -``` -sopel.cfg /etc -sopel.conf /usr/lib/tmpfiles.d -sopel.service /usr/lib/systemd/system -sopel@.service /usr/lib/systemd/system -``` - ## tox `tox.ini` and `toxfile.py` provide support for running Sopel's QA automation diff --git a/contrib/sopel.cfg b/contrib/sopel.cfg deleted file mode 100644 index af2c04c7c4..0000000000 --- a/contrib/sopel.cfg +++ /dev/null @@ -1,19 +0,0 @@ -# Default sopel configuration file for Fedora -# For information related to possible configuration values see -# https://sopel.chat/docs/config.html#the-core-configuration-section -# https://sopel.chat/usage/plugin-configuration/ -# -# IMPORTANT NOTE! -# You must delete the not_configured line in order for the bot to work, -# otherwise it will refuse to start. -[core] -nick=sopel -not_configured=True -host=irc.libera.chat -port=6697 -use_ssl=True -verify_ssl=True -owner= -logdir=/var/log/sopel -pid_dir=/run/sopel -homedir=/var/lib/sopel diff --git a/contrib/sopel.conf b/contrib/sopel.conf deleted file mode 100644 index bbff2ae1e3..0000000000 --- a/contrib/sopel.conf +++ /dev/null @@ -1,2 +0,0 @@ -# Sopel temporary directory setup -d /run/sopel 0755 sopel sopel - diff --git a/contrib/sopel.service b/contrib/sopel.service deleted file mode 100644 index 4666fd1cb5..0000000000 --- a/contrib/sopel.service +++ /dev/null @@ -1,17 +0,0 @@ -[Unit] -Description=Sopel IRC bot -Documentation=https://sopel.chat/ -After=network-online.target - -[Service] -Type=simple -User=sopel -PIDFile=/run/sopel/sopel-sopel.pid -ExecStart=/usr/bin/sopel -c /etc/sopel.cfg -Restart=on-failure -RestartPreventExitStatus=2 -RestartSec=30 -Environment=LC_ALL=en_US.UTF-8 - -[Install] -WantedBy=multi-user.target diff --git a/contrib/sopel@.service b/contrib/sopel@.service deleted file mode 100644 index 493a383507..0000000000 --- a/contrib/sopel@.service +++ /dev/null @@ -1,18 +0,0 @@ -[Unit] -Description=Sopel IRC bot -Documentation=https://sopel.chat/ -After=network-online.target -DefaultInstance=sopel - -[Service] -Type=simple -User=sopel -PIDFile=/run/sopel/sopel-%I.pid -ExecStart=/usr/bin/sopel -c /etc/sopel/%I.cfg -Restart=on-failure -RestartPreventExitStatus=2 -RestartSec=30 -Environment=LC_ALL=en_US.UTF-8 - -[Install] -WantedBy=multi-user.target diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000000..12f4f749cc --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,40 @@ +========================== +Frequently Asked Questions +========================== + +.. _faq-contact-us: + +How to contact us? +================== + +You can contact us by joining the development and community channel on IRC: + +* connect to the `libera.chat`__ network +* and join the ``#sopel`` channel + +We talk about the bot's development, and we answer questions from bot owners & +plugin authors as much as we can. We try to keep it as friendly as possible; +sometimes we also just chat about about non-development topics. + +All conversations are in English (except when someone swears in French). + +.. __: https://libera.chat/guides/connect + + +.. _faq-bug-report: + +How to report a bug? +==================== + +The best place to report a bug is to `open an issue on GitHub`__. We have +configured some templates to help and guide you through the process and +hopefully to make it easier for you. + +Before submitting your bug, you can `search existing issues`__ to see if there +is one open already. + +Do not hesitate to :ref:`contact us` if you are unsure about +your bug report. + +.. __: https://github.com/sopel-irc/sopel/issues/new/choose +.. __: https://github.com/sopel-irc/sopel/issues diff --git a/docs/source/index.rst b/docs/source/index.rst index c851d7ccee..942c6414da 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,28 +1,30 @@ .. title:: Sopel IRC Bot +============= Sopel IRC Bot ============= `Sopel `_ is a Python IRC bot framework. It is designed to enable easily writing new utilities and features for your IRC channels. + Quick links ------------ +=========== * `Latest releases `_ * `Source code `_ +* :doc:`faq` -.. - Eventually, add installation instructions to Sphinx docs? Documentation -------------- +============= .. toctree:: :maxdepth: 2 :titlesonly: run + faq plugin package tests diff --git a/docs/source/plugin/tutorials/configuration-and-setup.rst b/docs/source/plugin/tutorials/configuration-and-setup.rst index f5d5156bd2..20b7f1b41a 100644 --- a/docs/source/plugin/tutorials/configuration-and-setup.rst +++ b/docs/source/plugin/tutorials/configuration-and-setup.rst @@ -5,7 +5,7 @@ Configuration and plugin setup Maybe you :doc:`played with commands ` for your plugin and now you want to make your plugin configurable. If you run an instance of Sopel yourself, you probably had to open and edit its -:doc:`configuration` file. +:doc:`configuration` file. Usually located in the ``.sopel/`` folder under your home directory, the configuration file is an INI file with sections defined by Sopel's core and by @@ -107,7 +107,7 @@ declare and to setup your plugin configuration, and you can read more about :ref:`plugin configuration `, which includes a section about the configuration wizard as well. You can also see Sopel's own configuration in -:doc:`the configuration chapter `. +:doc:`the configuration chapter `. Once you are familiar with the concept, you can also read deeper into the reference documentation for the :mod:`sopel.config` module. diff --git a/docs/source/run.rst b/docs/source/run.rst index 5ed3f35c5f..750f98a4c2 100644 --- a/docs/source/run.rst +++ b/docs/source/run.rst @@ -1,7 +1,26 @@ +=============== Running the bot =============== +Welcome to this part of the documentation, dedicated to all who do or want to +run a Sopel instance. This guide will help you set up your instance and manage +your plugins and your configuration. + +.. note:: + + Sopel tries to be as simple as possible, however "simple" can be very + subjective, so do not hesitate to ask questions to the maintainers on IRC + (on the :ref:`#sopel channel` on libera.chat) or through + Sopel's `GitHub repository`__. This guide is far from perfect, and we + appreciate feedback to make it better for everyone. + .. toctree:: + :titlesonly: + run/install + run/plugin + run/service run/cli run/configuration + +.. __: https://github.com/sopel-irc/sopel/ diff --git a/docs/source/run/install.rst b/docs/source/run/install.rst new file mode 100644 index 0000000000..7e70bc971b --- /dev/null +++ b/docs/source/run/install.rst @@ -0,0 +1,139 @@ +============= +Install Guide +============= + +.. highlight:: shell + +Installation Requirements +========================= + +To install Sopel, you will need: + +* Python 3.8 or above +* Pip, the official Python package installer + +.. important:: + + Before installing Sopel, you should know which version of Python, and which + Python interpreter you are using for that. For instance, it can be named + ``python3`` or just ``python`` depending on your system and setup. In this + guide we will refer to the Python interpreter you want to use as + ``python3``. + +Official Release +================ + +The official release of Sopel is `available at PyPI`__. The +recommended way to install Sopel from pypi.org is to perform the following +command:: + + python3 -m pip install sopel + +This will ensure that Sopel is installed for the Python interpreter you want to +use. You do not need to have root access to install Sopel. To check that Sopel +is indeed installed, you can run the following line:: + + python3 -c "import sopel; print(sopel.__version__)" + +This will show the installed version of Sopel for this interpreter. + +When a new version of Sopel is released, you can update your install by reusing +the same command with the ``-U`` option (short for ``--upgrade``):: + + python3 -m pip install -U sopel + +You must restart Sopel for the update to take effect. + +.. __: https://pypi.org/project/sopel/ + +Installing from Source +====================== + +For development purposes or to test a future release, you may want to install +Sopel directly from its `source repository`__ on GitHub. To install from +source, first select the version you want to install, and refer to the +``README.rst`` file for instructions. + +We strongly recommend to use a virtualenv or other isolation mechanism so as to +prevent any conflicts with your system's Python interpreter and libraries. + +.. warning:: + + Although possible, source installations are not supported. If you install + from sources, you may encounter unexpected bugs and unstable behaviors, and + we fully expect you to either find a solution by yourself, revert to a + previous version, or wait for a fix without an ETA. + + However, we do appreciate :ref:`bug reports` (with logs and + configuration details) and feedback. In that case, + :ref:`reaching out to us on IRC` is the best approach. + +.. __: https://github.com/sopel-irc/sopel + + +First run +========= + +Once Sopel is installed, you should have access to a ``sopel`` command, as well +as :doc:`other commands `. + +.. note:: + + By default, ``pip`` will install the command in ``~/.local/bin/``, which + might not be on your ``PATH``. You will need to add this folder to your + ``PATH`` for your shell to see the command. + + For example, you could add this to your ``~/.profile`` file (works on + Ubuntu 22.04):: + + # set PATH so it includes user's private bin if it exists + if [ -d "$HOME/.local/bin" ] ; then + PATH="$HOME/.local/bin:$PATH" + fi + + Refer to your operating system's documentation for more information on how + to configure your ``PATH``. + +Initial Configuration +--------------------- + +To run the bot, you need a :doc:`configuration file `, which you +can create with the following command:: + + sopel configure + +This will run a wizard that helps you create a configuration file. It will +ask you questions to fill in the details. When you see something in ``[square +brackets]``, that's the default setting, and you can just hit Enter to keep +it. We recommend selecting a custom nick for your bot during configuration. + +This wizard doesn't cover every option, only the ones which are needed to get +the bot running. The :doc:`core config settings ` are all +documented if you want to make other tweaks. + +Finally, the wizard will ask you about configuration settings for plugins. This +will automatically detect what plugins you have available, and run their +configuration utility if they have one. + +Once you are done, you can always re-run the same command and accept the values +you already set and change only what you need. + +Start the Bot +------------- + +Once you have properly configured your bot, you are now ready to start it for +the first time. The command to do so is the following:: + + sopel start + +.. note:: + + Some IRC networks require nick registration or special configuration + for connecting. Refer to your IRC network for more information about + what steps may be necessary to run your bot there. + +Sopel will output log information informing you of its startup progress, such +as loading plugins, connecting to the network, and joining channels. + +To stop the bot, simply exit the process (e.g. with :kbd:`Control+c`) and +Sopel will ``QUIT`` IRC, perform its shutdown tasks, and gracefully exit. diff --git a/docs/source/run/plugin.rst b/docs/source/run/plugin.rst new file mode 100644 index 0000000000..dec7b5056a --- /dev/null +++ b/docs/source/run/plugin.rst @@ -0,0 +1,137 @@ +================ +Managing plugins +================ + +.. highlight:: shell + +Sopel is designed with plugins in mind: they add features/commands and can do +many things to make Sopel more useful or more fun to interact with on IRC. + +There are two main types of plugins you can add: + +* single file plugins that you drop into a folder +* packaged plugins that you install with ``pip`` + +A plugin can have its own configuration section, and may generate files or use +the database. + +.. note:: + + Make sure to read the documentation for the plugins you install and use. + + +Adding plugins +============== + +Install single file plugins +--------------------------- + +To add a single file plugin to your Sopel instance, copy the file into the +bot's ``plugins`` directory under the +:attr:`~sopel.config.core_section.CoreSection.homedir` directory. By default, +the plugin file should be copied into ``~/.sopel/plugins``. + +.. note:: + + Following the :doc:`systemd service example `, if your homedir is + ``/var/lib/sopel`` then your plugin directory is + ``/var/lib/sopel/plugins``. + +Start (or restart) your bot and Sopel will load the plugin automatically. + +Install packaged plugins +------------------------ + +Plugin authors might also publish their works as packages; you can find them by +searching PyPI, or by using your favorite search engine to search for +e.g. "sopel reminder plugin". + +You can install these packages with ``pip``, the same way it is recommended to +install Sopel. All you need is to install the plugin for the same Python +interpreter. + +For example, you can install the "remind" plugin from the ``sopel-remind`` +package:: + + python3 -m pip install sopel-remind + +This will install the plugin from PyPI where you can see `all the releases`__ +of this package. + +.. note:: + + Each plugin can have specific system dependencies or other requirements + that you need to take care of when installing it. Refer to the plugin's + documentation for more details. + +.. __: https://pypi.org/project/sopel-remind/ + + +Enabling or disabling plugins +============================= + +By default, any plugins that Sopel can load will be automatically enabled: it +is true for all types of plugins (built-in, single file, or packaged plugins). +You can control this behavior by disabling some plugins, or enabling only some +plugins. + +You can disable a plugin by using the ``sopel-plugins disable`` command line, +e.g. to disable the remind plugin mentioned before:: + + sopel-plugins disable remind + +This will add the plugin to the +:attr:`~sopel.config.core_section.CoreSection.exclude` list. The next time the +bot starts (or restarts), the plugin won't be loaded. + +You can re-enable a plugin by using the ``sopel-plugins enable`` command line, +e.g. to re-enable the remind plugin:: + + sopel-plugins enable remind + +Which will remove the plugin from the ``exclude`` list. The plugin will be +loaded as before the next time the bot starts (or restarts). + +Enable-only plugins +------------------- + +By default, all plugins are enabled, and you disable plugins one by one. +However, you may want to enable only a set of plugins, and disable every other +one by default. + +To do so, the enable command has a ``--allow-only`` option: this will add the +plugin to the :attr:`~sopel.config.core_section.CoreSection.enable` list:: + + sopel-plugins enable --allow-only remind + +When you start the bot (or restart), the bot will load the plugins from the +``enable`` list, and **only these plugins**. + + +Configuring plugins +=================== + +Some (but not all!) plugins define their own configuration sections so you can +configure their behavior. If a plugin supports it, you may be able to use the +configuration wizard to edit the configuration of the plugin:: + + sopel-plugins configure remind + +Alternatively, you can edit your configuration file and follow the plugin's +documentation to set the appropriate options and values. Here's an +example configuration of the `sopel-remind plugin`__, which defines the +``[remind]`` section for its own use: + +.. __: https://github.com/sopel-irc/sopel-remind + + +.. code-block:: INI + + [core] + # Sopel core's section + + [remind] + # remind's section + location = /path/to/remind/location + +Sopel must be restarted after making changes to the configuration file. diff --git a/docs/source/run/service.rst b/docs/source/run/service.rst new file mode 100644 index 0000000000..8ca1a93f45 --- /dev/null +++ b/docs/source/run/service.rst @@ -0,0 +1,174 @@ +==================== +Running as a service +==================== + +Now that you can run the bot, you probably want it to run forever in the +background of your system. While there are many ways to do so, there are a few +steps and requirements that remain the same to properly run Sopel as a service. + + +Requirements to run a service +============================= + +Sopel needs the following: + +* a non-root user to run as +* read/write access to its configuration file +* a writable pid directory + (:attr:`~sopel.config.core_section.CoreSection.pid_dir`) +* a writable logs directory + (:attr:`~sopel.config.core_section.CoreSection.logdir`) +* a writable data directory + (:attr:`~sopel.config.core_section.CoreSection.homedir`) + +.. important:: + + Do **not** run Sopel as the **root** user. And avoid if possible to run + with a privileged user. + + +Running with systemd +==================== + +`systemd`__ is a service manager used by Ubuntu and most Debian-derived +Linux distributions. Here is an example of a service unit file to run Sopel as +a service, placed at ``/etc/systemd/system/sopel.service``: + +.. code-block:: systemd + + [Unit] + Description=Sopel IRC bot + Documentation=https://sopel.chat/ + After=network-online.target + + [Service] + Type=simple + User=sopel + RuntimeDirectory=sopel + StateDirectory=sopel + LogsDirectory=sopel + PIDFile=/run/sopel/sopel.pid + ExecStart=/home/sopel/.local/bin/sopel start + Restart=on-failure + RestartPreventExitStatus=2 + RestartSec=30 + Environment=LC_ALL=en_US.UTF-8 SOPEL_CONFIG_DIR=/etc/sopel + + [Install] + WantedBy=multi-user.target + +.. __: https://systemd.io/ + +For this service to work you will need the following: + +* to create a ``sopel`` user +* to install ``sopel`` with that user (or to change the path in the + ``ExecStart``) +* to place your Sopel configuration file into ``/etc/sopel/default.cfg``, and + to setup its access rights so that the ``sopel`` user can read and write it +* and to edit the ``[core]`` section of this configuration file to set the + appropriate paths: + + .. code-block:: ini + + [core] + homedir = /var/lib/sopel + pid_dir = /run/sopel + logdir = /var/log/sopel + +These paths are required for Sopel to know where to put its files (data, cache, +PID file, logs, etc.). + +And with that, you will be able to start/stop your bot with: + +* ``systemctl start sopel`` to start the service +* ``systemctl stop sopel`` to stop the service + +Once you are sure it works, you can enable the service with +``systemctl enable sopel`` so that the service will start automatically at +boot. + +.. seealso:: + + There is more to say about systemd, its service unit files, and the + ``systemctl`` command. Be sure to read `systemd.unit's documentation`__ for + more information. + +.. __: https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html + + +Example of configuration for Libera Chat +======================================== + +To put everything together, let's say you want to run a bot for your channel +on the `libera.chat network`__. For that, here is a configuration file you will +need to put at ``/etc/sopel/default.cfg``: + +.. code-block:: ini + + [core] + nick = + host = irc.libera.chat + port = 6697 + use_ssl = yes + verify_ssl = yes + owner = + channels = + "#yourchannel" + homedir = /var/lib/sopel + pid_dir = /run/sopel + logdir = /var/log/sopel + +Make sure to replace ```` with your bot's nick, as "Sopel" is +already taken; and set your own nick as the owner instead of ````. + +.. __: https://libera.chat/ + + +Multiple instances +================== + +You can create a ``sopel@.service`` file that is a multi-instance systemd +template. It follows the same general structure as the single instance from +above, and uses the same user running all instances. + +The following file should be placed at ``/etc/systemd/system/sopel@.service``: + +.. code-block:: systemd + + [Unit] + Description=Sopel IRC bot + Documentation=https://sopel.chat/ + After=network-online.target + DefaultInstance=sopel + + [Service] + Type=simple + User=sopel + RuntimeDirectory=sopel + StateDirectory=sopel + LogsDirectory=sopel + PIDFile=/run/sopel/sopel-%I.pid + ExecStart=/home/sopel/.local/bin/sopel start -c %I.cfg + Restart=on-failure + RestartPreventExitStatus=2 + RestartSec=30 + Environment=LC_ALL=en_US.UTF-8 SOPEL_CONFIG_DIR=/etc/sopel + + [Install] + WantedBy=multi-user.target + +To start a service, you need to place the name of the configuration file you +want to use in the command, e.g. to run with the ``libera`` configuration: + +* ``systemctl start sopel@libera.service`` to start the bot +* ``systemctl stop sopel@libera.service`` to stop the bot + +Notice the ``@libera`` in each command line: it means the configuration file +will be ``/etc/sopel/libera.cfg``, and the PID file will be set at +``/run/sopel/sopel-libera.pid``. + +.. note:: + + The default instance name is ``sopel``, for the ``/etc/sopel/sopel.cfg`` + configuration file, and not ``/etc/sopel/default.cfg``.