Add READMEv0.1

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

1 files changed, 140 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..6607e90
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,140 @@
+
+                                _____        _____   
+                            ___|\    \   ___|\    \  
+                           /    /\    \ |    |\    \ 
+                          |    |  |    ||    | |    |
+                          |    |  |____||    | |    |
+                          |    |   ____ |    | |    |
+                          |    |  |    ||    | |    |
+                          |\ ___\/    /||____|/____/|
+                          | |   /____/ ||    /    | |
+                           \|___|    | /|____|____|/ 
+                             \( |____|/   \(    )/   
+                              '   )/       '    '    
+                                  '                  
+                          .__                 .___        .__   .__         
+    ____   ___.__.  ____  |  |__    ____    __| _/  ____  |  |  |__|  ____  
+  _/ ___\ <   |  |_/ ___\ |  |  \ _/ __ \  / __ | _/ __ \ |  |  |  |_/ ___\ 
+  \  \___  \___  |\  \___ |   Y  \\  ___/ / /_/ | \  ___/ |  |__|  |\  \___ 
+   \___  > / ____| \___  >|___|  / \___  >\____ |  \___  >|____/|__| \___  >
+       \/  \/          \/      \/      \/      \/      \/                \/ 
+
+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:
+
+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.
+
+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.
+
+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:
+
+- ACID (Automated Container & Image Daemon): Back-end service that monitors
+sources and interacts with the node's host Docker daemon.
+
+- [COMING SOON]: Web front-end for monitoring build jobs and service status.
+
+
+
+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.
+
+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.
+
+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.
+
+cychedelic will launch in the background and begin rebuilding the configured
+services.  The service should persist through reboots of the host.
+
+
+
+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.
+
+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
+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
+networks, which might break previous behavior.
+
+Especially, renaming the cychedelic entry after initial use is problematic, as
+the removal of the old-named entry causes cychedelic to be stopped.  At this
+point, no further processing will occur without manual intervention.
+
+
+
+Security Considerations
+=======================
+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.
+
+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
+legitimate use-cases for mounting host files.  For example, cychedelic mounts
+the host's docker daemon socket (/var/run/docker.sock) in order to control its
+managed containers.
+
+For this reason, users should not allow write access to the repositories used
+for cychedelic or its sources by anyone who should not possess root access on
+the cychedelic host node!
+
+It may still be safe to pull and run images built and maintained by third
+parties.  However, it is strongly advised to only use a trusted
+docker-compose.yml file, whose access is restricted as above.  Please audit your
+third party code!
+
+
+
+Service Conflict Considerations
+===============================
+All services are deployed to the host running cychedelic, so any finite,
+exclusive resources can not be shared between them.  For example, only one
+container may listen on a given network port.  Plan your infrastructure
+accordingly.
+
+This limitation is especially noticable if attempting to host multiple web-based
+services on your node, since only one container can bind port 80 or 443.  In
+this specific case, the use of a reverse HTTP proxy is recommended.
+
+The default docker-compose.yml file provided with cychedelic is written to be
+used alongside the nginxproxy/nginx-proxy service.  An extra entry in the ACID
+config file is required to install this service.
+
+
+
+cychedelic is public domain software, per the UNLICENSE <http://unlicense.org/>.