From adf930b531b477cd83e00e82c5d1d218395e47f1 Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@edbob.org>
Date: Mon, 31 Oct 2022 20:36:40 -0500
Subject: [PATCH] Add some minimal docs on Supervisor

needed a place to record how XML-RPC setup should go
---
 docs/base/index.rst               |  2 +-
 docs/base/supervisor.rst          | 11 ------
 docs/base/supervisor/index.rst    | 10 ++++++
 docs/base/supervisor/overview.rst | 12 +++++++
 docs/base/supervisor/setup.rst    | 59 +++++++++++++++++++++++++++++++
 5 files changed, 82 insertions(+), 12 deletions(-)
 delete mode 100644 docs/base/supervisor.rst
 create mode 100644 docs/base/supervisor/index.rst
 create mode 100644 docs/base/supervisor/overview.rst
 create mode 100644 docs/base/supervisor/setup.rst

diff --git a/docs/base/index.rst b/docs/base/index.rst
index 2323063..54f8946 100644
--- a/docs/base/index.rst
+++ b/docs/base/index.rst
@@ -15,7 +15,7 @@ Base Layer
    scripts
    email/index
    cron
-   supervisor
+   supervisor/index
    filemon/index
    mailmon
    upgrades
diff --git a/docs/base/supervisor.rst b/docs/base/supervisor.rst
deleted file mode 100644
index d99e6bd..0000000
--- a/docs/base/supervisor.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-
-Supervisord
-===========
-
-TODO
-
-
-Linux Only...
--------------
-
-TODO
diff --git a/docs/base/supervisor/index.rst b/docs/base/supervisor/index.rst
new file mode 100644
index 0000000..01d8e1b
--- /dev/null
+++ b/docs/base/supervisor/index.rst
@@ -0,0 +1,10 @@
+
+Supervisor
+==========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview
+   setup
diff --git a/docs/base/supervisor/overview.rst b/docs/base/supervisor/overview.rst
new file mode 100644
index 0000000..5cc8e92
--- /dev/null
+++ b/docs/base/supervisor/overview.rst
@@ -0,0 +1,12 @@
+
+Overview
+========
+
+`Supervisor`_ is a generic process control system, which may be used
+to manage Rattail daemons in a standard way on the Linux server.
+While not technically required, it's generally recommended and some
+Rattail docs may assume its presence.
+
+.. _Supervisor: http://supervisord.org/
+
+See :doc:`setup` for installation and configuration.
diff --git a/docs/base/supervisor/setup.rst b/docs/base/supervisor/setup.rst
new file mode 100644
index 0000000..1ce2674
--- /dev/null
+++ b/docs/base/supervisor/setup.rst
@@ -0,0 +1,59 @@
+
+.. highlight:: sh
+
+=======
+ Setup
+=======
+
+Basic install of Supervisor itself::
+
+   sudo apt install supervisor
+
+
+Adding a Process [Group]
+========================
+
+TODO
+
+
+User Access
+===========
+
+By default only the ``root`` user can control Supervisor, e.g.::
+
+   sudo supervisorctl status
+
+TODO: describe how to give e.g. ``rattail`` user access as well
+
+
+Configuring XML-RPC
+===================
+
+Supervisor can provide a XML-RPC interface, with which Rattail can
+communicate "directly" instead of invoking shell commands.
+
+To enable this interface, create a file at
+e.g. ``/etc/supervisor/conf.d/supervisor.conf`` and in it put:
+
+.. code-block:: ini
+
+   [inet_http_server]
+   port = 127.0.0.1:8127
+   username = myuser
+   password = mypass
+
+Choose whichever credentials you like for the above; use the same ones
+in the remaining steps.
+
+Once the above file is in place, restart::
+
+   sudo systemctl restart supervisor
+
+Now within your Rattail config, set the Supervisor URL:
+
+.. code-block:: ini
+
+   [rattail]
+   supervisorctl_url = http://myuser:mypass@localhost:8127/RPC2
+
+You may need to restart the Rattail app(s) as well.