More documentation

README.md

-# abuildd
-
-an Alpine archive management software replacement
-
-
-## synopsis
-
-`abuildd` contains multiple components that replaces the entire Alpine archive management
-software.  These are:
-
- * `abuildd-build`: runs a build and stages artifacts to a designated location
-
- * `abuildd-agentd`: runs as an agent and consumes MQTT messages for build requests
-
- * `abuildd-collect`: retrieves artifacts from a build server for a specific build
-
- * `abuildd-compose`: gathers all collected artifacts and composes a repository or
-                      distribution
-
- * `abuildd-enqueue`: enqueues new packages for building with dependency resolution
-
- * `abuildd-git-hook`: runs `abuild-enqueue` as necessary when new git commits are
-                       received
-
- * `abuildd-monitord`: a monitoring daemon which watches the MQTT server for feedback from
-                       the build servers
-
- * `abuildd.webhook`: a webhook implementation which enqueues new packages based on
-                      changeset notifications
-
- * `abuildd.status`: an `aiohttp.web` application which shows current status of the
-                     build servers, also includes `abuildd.webhook`
-
-`abuildd` depends on a preconfigured postgresql database and mqtt server, you can use any
-mqtt server you wish for the task (mosquitto, rabbitmq, etc.).  It also depends on bubblewrap
-being installed for sandboxing the build.
-
-
-## PPAs
-
-`abuildd` can be configured to build PPAs, as well as official repos.  See the `abuildd-git-hook`
-documentation for more details.  Alternatively, a Github webhook can be found in the
-`abuildd.webhook` module.  The webhook module requires gunicorn and aiohttp.
-
-## Webhook
-
-Still a work in progress - mostly finished but needs an installer. To set it up and play
-with it, here's a quick and dirty rundown:
-
-```
-# mkdir /etc/abuildd
-# cp conf/*.ini /etc/abuildd
-# $EDITOR /etc/abuildd/*.ini
-$ echo 'CREATE DATABASE abuildd;' | psql -U postgres
-$ psql -U postgres -d abuildd -f abuildd/abuildd.sql
-$ virtualenv /path/to/new/venv
-$ source /path/to/new/venv/bin/activate
-(venv) $ pip install hbmqtt aiohttp asyncpg pyirc
-(venv) $ export PYTHONPATH="$(pwd):/path/to/py3-abuild:$PYTHONPATH"
-```
-
-Then create a bare git clone for each project you want to support. A project's name is
-simply its git URL with slashes replaced by full stops, e.g.
-`code.foxkit.us.sroracle.packages.git`.
-
-```
-(venv) $ git clone --bare https://git/clone/url.git git.clone.url.git
-(venv) $ /path/to/webhook.py
-```
-
-The webhook can be added to a GitLab project by going to Settings > Web Hooks. Currently,
-"Push Events", "Comments" (on merge requests; "notes" internally), and "Merge Request
-Events" are supported.
-
-

README.rst

+README for abuildd
+==================
+
+an Alpine archive management software replacement
+
+:Authors:
+  * **William Pitcock**, original developer
+  * **Max Rees**, maintainer
+:Status:
+  Alpha
+:Copyright:
+  © 2017-2018 William Pitcock and Max Rees. MIT open source licence.
+
+Synopsis
+--------
+
+``abuildd`` contains multiple components that replaces the entire Alpine
+archive management software. These are:
+
+   * ``abuildd-build``: runs a build and stages artifacts to a
+     designated location
+   * ``abuildd-agentd``: runs as an agent and consumes MQTT messages for
+     build requests
+   * ``abuildd-collect``: retrieves artifacts from a build server for a
+     specific build
+   * ``abuildd-compose``: gathers all collected artifacts and composes a
+     repository or distribution
+   * ``abuildd-enqueue``: enqueues new packages for building with
+     dependency resolution
+   * ``abuildd-git-hook``: runs ``abuild-enqueue`` as necessary when new git
+     commits are received
+   * ``abuildd-monitord``: a monitoring daemon which watches the MQTT server
+     for feedback from the build servers
+   * ``abuildd-webhook``: a webhook implementation which enqueues new
+     packages based on changeset notifications
+   * ``abuildd-status``: an ``aiohttp.web`` application which shows the
+     current status of the build servers, also includes ``abuildd-webhook``
+
+Dependencies
+------------
+
+``abuildd`` depends on a preconfigured PostgreSQL database and mqtt server, you
+can use any mqtt server you wish for the task (mosquitto, rabbitmq, etc.). It
+also depends on bubblewrap being installed for sandboxing the build.
+
+Base set
+   * Python 3.6+
+   * PostgreSQL server
+   * MQTT broker
+   * `hbmqtt <https://hbmqtt.readthedocs.io/en/latest/>`_
+   * `asyncpg <https://magicstack.github.io/asyncpg/current/>`_
+   * `py3-abuild <https://code.foxkit.us/sroracle/py3-abuild>`_
+
+``abuildd-webhook``, ``abuildd-status``
+   * `aiohttp <https://aiohttp.readthedocs.io/en/stable/>`_
+
+``abuildd-agentd``
+   * `bubblewrap <https://github.com/projectatomic/bubblewrap>`
+
+PPAs
+----
+
+``abuildd`` can be configured to build PPAs, as well as official repos. See
+the ``abuildd-git-hook`` documentation for more details. Alternatively, a
+GitLab webhook can be found in the ``abuildd.webhook`` module.

doc/quickstart.rst

+Getting started with abuildd
+============================
+
+abuildd configuration
+---------------------
+
+The files in the ``conf/`` directory are example configuration files for use
+with abuildd. The ``INI`` files are copied to ``/etc/abuildd`` and changed as
+appropriate. The names of the files and the distribution of content between
+them is completely arbitrary and can be customized as you wish - the
+configuration manager globs for ``/etc/abuildd/*.ini`` and reads them in sorted
+order. Each configuration option is documented within the example configuration
+files, along with their defaults. Configuration options are referred to as
+``<section name>.<option name>``, for example ``irc.mqtt`` for the ``mqtt``
+option in the ``[irc]`` section. Comments start with a semicolon (``;``) and
+are not allowed on the same line as assignments. Assignments can span multiple
+lines as long as the additional lines after the assignment are indented. Blank
+lines are included in the assignments, and so assignments continue until the
+next comment or assignment.
+
+The ``conf/mosquitto-acl`` file is an example access control list file for use
+with the `mosquitto(8) <https://mosquitto.org/>` MQTT broker. See the
+``doc/mosquitto.rst`` file for more information.
+
+.. code-block:: console
+
+   # mkdir /etc/abuildd
+   # cp conf/*.ini /etc/abuildd
+   # $EDITOR /etc/abuildd/*.ini
+
+MQTT configuration
+------------------
+See the ``doc/mqtt.rst`` file.
+
+.. code-block:: console
+
+   # $EDITOR $(grep -l '^;mqtt =' conf/*.ini)
+
+Database configuration
+----------------------
+
+.. code-block:: console
+
+   $ echo 'CREATE DATABASE abuildd;' | psql -U postgres
+   $ psql -U postgres -d abuildd -f abuildd.sql
+   # $EDITOR /etc/abuildd/database.ini

doc/webhook.rst

+Setting up the webhook for use with GitLab
+==========================================
+
+Create a bare git clone for each GitLab project you would like to receive build
+requests from. The name of the clone should be the clone URI with slashes
+replaced with full stops. Then the webhook should be run from the directory
+that contains the clones. For example:
+
+.. code-block:: console
+
+   $ git clone --bare https://code.foxkit.us/sroracle/packages.git code.foxkit.us.sroracle.packages.git
+   $ git clone --bare https://code.foxkit.us/adelie/packages.git code.foxkit.us.adelie.packages.git
+   $ /path/to/webhook.py
+
+The webhook can be added to a GitLab project by going to Settings > Web Hooks.
+Currently, "Push Events", "Comments" (on merge requests; "notes" internally),
+and "Merge Request Events" are supported.