Update README

Signed-off-by: Malfurious <m@lfurio.us>

1 files changed, 130 insertions, 36 deletions

diff --git a/README b/README
index 6607e90..b2c2d57 100644
--- a/README
+++ b/README
@@ -20,75 +20,80 @@
        \/  \/          \/      \/      \/      \/      \/                \/ 
 
 cychedelic is a service-oriented continuous deployment system, developed using
-the suckless philosophy, which is based on git and docker-compose.  There are
-two main functionalities which cychedelic aims to provide:
+the suckless philosophy, based on git and docker-compose.  There are two main
+functionalities which cychedelic aims to provide:
 
 1. Continuous Deployment: Automatically build and deploy services from a git
-repository as updates are pushed out by the developers.  cychedelic will monitor
-any number of git sources which are defined in its central configuration.  These
-services are deployed to the same node which is running cychedelic.
+repository as updates are made available.  cychedelic will monitor any number of
+git sources which are defined in its central configuration.  These services are
+deployed to the same node which is running cychedelic.
 
 2. Service image maintenance: Periodically rebuild images from scratch to
-incorporate changes from new base images and install the latest available
-packages.  While cychedelic can be configured to pull all images from a registry,
-it is primarily intended to act as the build infrastructure, pulling code
-directly from git.  Maintenance is performed to ensure that services are always
-running in an up-to-date environment, even if the code has not been updated in
-a while.
+incorporate changes from base images and install the latest available packages.
+While cychedelic can be configured to pull all images from a registry, it is
+primarily intended to act as the build infrastructure, pulling code directly
+from git.  Maintenance is performed to ensure that services are always running
+in an up-to-date environment, even if the code hasn't been updated in a while.
 
 During maintenance, cychedelic will also prune the system of unused containers,
 images, etc., but will _never_ delete any docker volumes.
 
-The cychedelic system is made up of various components:
+The following components make up cychedelic:
 
 - ACID (Automated Container & Image Daemon): Back-end service that monitors
-sources and interacts with the node's host Docker daemon.
+sources and interacts with the node's host docker daemon.
 
-- [COMING SOON]: Web front-end for monitoring build jobs and service status.
+- DMT (Display for Monitoring log Text): Web front-end for monitoring build jobs
+and service status information.
 
 
 
 Configuration and Installation
 ==============================
-cychedelic is configured by modifying the ACID config file (acid/config.sh).
-The config is statically baked into the docker image.  These changes should be
-committed and pushed to a git server which is accessible by the node to which
-you wish to install cychedelic.
+cychedelic is configured via the following files:
+
+    docker-compose.yml (Main service deployment configuration)
+    acid/config.sh (ACID daemon config / managed service list)
+    dmt/config.sh (DMT interface config)
+
+Configurations are statically baked into service docker images.  Any changes
+should be committed and pushed to a git server which is accessible by the node
+you wish to install to.
 
 While configuring cychedelic, keep in mind that in addition to your other
-docker-based services, cychedelic is also designed to keep itself up-to-date as
-well.  Therefore, future configuration changes and patches to the code may be
-rolled out by simply pushing them to the repository and branch you specify in
-your config file.
+services, cychedelic is designed to also keep itself up-to-date as well.
+Therefore, future configuration changes or code patches may be rolled out by
+simply pushing them to the repository and branch you specify.
 
 To bootstrap an initial installation of cychedelic on a docker host, clone your
 configuration on the host and run:
 
 $ docker compose up --detach --build
 
-Note: You may also need to specify a value for --project-name if you have
-changed the name of "cychedelic" in your config file.
+Note: You may also need to give a value for `--project-name` if you have changed
+the name of "cychedelic" in your ACID config file.
 
 cychedelic will launch in the background and begin rebuilding the configured
-services.  The service should persist through reboots of the host.
+services.  The service should persist through reboots of the host.  You may
+delete the git clone after running the initial `docker compose up` command.
 
 
 
-Guest Service Configuration
-===========================
-cychedelic utilizes docker-compose as a configuration medium for guest services.
-Each entry in the config file corresponds to exactly one docker-compose YML
-config file.  Services are built and executed according to the YML file found in
-the external git source repositories.
+Managed Services
+================
+cychedelic utilizes docker-compose as the configuration medium for guest
+services.  Each entry in $CYCHE_SERVICES (ACID config file) corresponds to one
+docker-compose YAML file.  Services are built and executed according to the YAML
+file found in the external git repositories.
 
 When new entries are added, the corresponding services are brought up the next
 time cychedelic is restarted (which is triggered immediately by the config
 change).  When entries are removed, services are stopped on the next restart.
 
-In general, any property stored in the ACID config may be seamlessly changed at
+In general, any property stored in $CYCHE_SERVICES may be seamlessly changed at
 any time.  However, service name changes should be performed with care.  A name
 change is seen as the removal of the service, and addition of a new one under
-its new name.  This will cause the services to use different volumes and
+its new name.  This will cause the service to use different volumes and
 networks, which might break previous behavior.
 
 Especially, renaming the cychedelic entry after initial use is problematic, as
@@ -97,11 +102,79 @@ point, no further processing will occur without manual intervention.
 
 
 
-Security Considerations
-=======================
+Monitoring
+==========
+cychedelic exposes a web interface for monitoring builds and service status.
+The jobs display is designed to sync with the server and remain up-to-date while
+unattended.  This page allows you to see build logs and results in real time, as
+well as download full logs for local use.  See cychedelic's "docker-compose.yml"
+for some required configuration steps necessary to use the DMT web interface.
+
+
+
+API
+===
+Some information available through the interactive web interface is also
+queryable through an HTTP API.  The following are supported endpoints.
+
+    http://YOUR_SERVER/api/status
+        Returns a JSON object with the following fields:
+            "version"
+                String identifying the server version / instance.  Its value is
+                unspecified.  However, a changed in the returned value indicates
+                a change in the server software.
+            "active"
+                Boolean which is true if any build job, deployment, or
+                maintenance task is ongoing.  False otherwise.
+            "job"
+                Integer specifying the active job number, if any.  When no job
+                is in progress, this value is -1.
+            "newest"
+                Integer specifying the most recent job available on the system.
+            "oldest"
+                Integer specifying the least recent job available on the
+                system.  It can be assumed that all jobs numbered
+                `oldest` <= x <= `newest` are available for query.
+
+    http://YOUR_SERVER/api/job/{NUMBER}
+        Returns a JSON object with the following fields:
+            "job"
+                Integer specifying the job number.  This is {NUMBER} if given.
+                Otherwise this is the number of the latest available job.  All
+                other fields in the object pertain to this job number.
+            "hash"
+                String containing the git commit hash job was initiated from.
+            "reason"
+                String specifying the reason which caused this job to execute.
+                Possible values are:
+                    "event": Usually a push event, but is used for any case
+                    where the deployed version is out-of-date.
+                    "maint": Forced maintenance build (even if deployed version
+                    is up-to-date).
+                    "remove": The service is being uninstalled from the host.
+            "service"
+                String containing the name of the service being built.
+            "time"
+                Integer specifying the timestamp the job started (UNIX epoch).
+            "result"
+                String specifying the outcome of the job.  Possible values are:
+                    "active": Job is still executing.
+                    "fail": Job has failed and did not deploy.
+                    "pass": Job has succeeded and is deployed.
+            "log"
+                String containing a tail of the raw job log file (log preview).
+
+    http://YOUR_SERVER/api/log/{NUMBER}
+        Returns as plaintext, the full job log of {NUMBER} (if given).
+        Otherwise, the log of the latest available job is returned.
+
+
+
+Security Consideration: Write Access
+====================================
 Docker compose allows the specification of bind mount volumes from the host into
 service containers.  cychedelic is not a docker-in-docker solution; it manages
-containers on the host server as siblings to itself.
+containers on the host as siblings to itself.
 
 Bind mounts can be used to leak information or gain root access on the host
 system!  This functionality can not be globally disabled, as there are some
@@ -120,6 +193,27 @@ third party code!
 
 
 
+Security Consideration: Read Access
+===================================
+By default, cychedelic makes the output of `docker-compose build` available to
+the public through its web interface for all automated deployments.  If these
+build logs contain visible secrets, they are leaked!
+
+If this impacts you, one solution is to simply not run the web interface.  This
+is accomplished by removing its entry in "docker-compose.yml".  Similar
+information can still be obtained with SSH access by querying the docker daemon
+manually.
+
+However, a more granular approach might make more sense.  For instance, you
+might opt to patch-out the ability to retrive full logs, but still use the web
+interface to monitor results.  You could configure the log tails to be smaller
+than their default size, reducing the risk of information leak while leaving
+useful error messages visible.  Furthermore, you could even patch-in an
+authentication feature, and leave full functionality intact for authorized
+users only.
+
+
+
 Service Conflict Considerations
 ===============================
 All services are deployed to the host running cychedelic, so any finite,